Embedded Systems Learning Academy - User contributions [en]

F21: ACE MARIO

2021-12-18T08:08:00Z

Proj user7: /* Game Task boundry diagram */

[[File:Super mario.JPG|right|400px|thumb|MARIO GAME]]
[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version 'Ace Mario' of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram : ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|300px|thumb|center|Mario Game FlowChart]]

=== Game Task boundry diagram : ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is a fantastic resource for planning out levels, background, and designing characters of the game . Images drawn using mtPaint can be converted into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Project Learnings ==

*Creating various Mario and Background images using MT-paint and Python scripts helped us in achieving better Graphics precision.
*Creating immersive Background graphics when Mario is traversing through the green bushes .
*Establishing board to board communication via Bluetooth module and optimizing the response time between the Matrix controller and joystick.
*Concepts of FreeRTOS , Communication using UART and basic learning helped us .

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position
*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T08:07:51Z

Proj user7: /* Game work Flow Diagram */

[[File:Super mario.JPG|right|400px|thumb|MARIO GAME]]
[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version 'Ace Mario' of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram : ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|300px|thumb|center|Mario Game FlowChart]]

=== Game Task boundry diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is a fantastic resource for planning out levels, background, and designing characters of the game . Images drawn using mtPaint can be converted into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Project Learnings ==

*Creating various Mario and Background images using MT-paint and Python scripts helped us in achieving better Graphics precision.
*Creating immersive Background graphics when Mario is traversing through the green bushes .
*Establishing board to board communication via Bluetooth module and optimizing the response time between the Matrix controller and joystick.
*Concepts of FreeRTOS , Communication using UART and basic learning helped us .

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position
*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T08:07:28Z

Proj user7: /* Game work Flow Diagram */

[[File:Super mario.JPG|right|400px|thumb|MARIO GAME]]
[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version 'Ace Mario' of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|300px|thumb|center|Mario Game FlowChart]]

=== Game Task boundry diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is a fantastic resource for planning out levels, background, and designing characters of the game . Images drawn using mtPaint can be converted into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Project Learnings ==

*Creating various Mario and Background images using MT-paint and Python scripts helped us in achieving better Graphics precision.
*Creating immersive Background graphics when Mario is traversing through the green bushes .
*Establishing board to board communication via Bluetooth module and optimizing the response time between the Matrix controller and joystick.
*Concepts of FreeRTOS , Communication using UART and basic learning helped us .

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position
*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T08:00:09Z

Proj user7: /* Game Graphics Implementation */

[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version called ==Ace Mario== of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies the victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|500px|thumb|center|Mario Game FlowChart]]

=== Game work Flow Diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is a fantastic resource for planning out levels, background, and designing characters of the game . Images drawn using mtPaint can be converted into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Project Learnings ==

*Creating various Mario and Background images using MT-paint and Python scripts helped us in achieving better Graphics precision.
*Creating immersive Background graphics when Mario is traversing through the green bushes .
*Establishing board to board communication via Bluetooth module and optimizing the response time between the Matrix controller and joystick.
*Concepts of FreeRTOS , Communication using UART and basic learning helped us .

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position
*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T07:59:21Z

Proj user7: /* Testing & Technical Challenges */

[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version called ==Ace Mario== of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies the victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|500px|thumb|center|Mario Game FlowChart]]

=== Game work Flow Diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is fantastic resource for planning out levels ,background and designing characters of game .Images drawn using mtPaint can be convert into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Project Learnings ==

*Creating various Mario and Background images using MT-paint and Python scripts helped us in achieving better Graphics precision.
*Creating immersive Background graphics when Mario is traversing through the green bushes .
*Establishing board to board communication via Bluetooth module and optimizing the response time between the Matrix controller and joystick.
*Concepts of FreeRTOS , Communication using UART and basic learning helped us .

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position
*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T07:58:18Z

Proj user7: /* Graphics development */

[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version called ==Ace Mario== of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies the victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|500px|thumb|center|Mario Game FlowChart]]

=== Game work Flow Diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is fantastic resource for planning out levels ,background and designing characters of game .Images drawn using mtPaint can be convert into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position
*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T07:58:00Z

Proj user7: /* Testing & Technical Challenges */

[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version called ==Ace Mario== of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies the victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|500px|thumb|center|Mario Game FlowChart]]

=== Game work Flow Diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is fantastic resource for planning out levels ,background and designing characters of game .Images drawn using mtPaint can be convert into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Testing & Technical Challenges ==

=== Graphics development ===
* Creating a motion effect for Mario traversal was a big challenge and the visual effect of Jump and Walk
Another trouble was running collision detection when Mario is not moving from his fixed position

*Came up with a solution of having whole display UI as a single matrix and traversing it as per Jump or forward movement.
Same position Jump and screen traversal should happen at the same time.

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T07:56:15Z

Proj user7: /* LED Matrix */

[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version called ==Ace Mario== of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies the victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"|
[https://www.linkedin.com/in/shreevats-gadhikar-56b523149/ Shreevats Gadhikar]
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== Game work Flow Diagram ===
Game logic gets triggered whenever a user selects the switch button on Joystick. The whole game flow is bounded by two essential conditions which are available time span and Lives. The user is supposed to finish the victory path by avoiding all the hurdles in his path.

[[File:Mario Game flow.png|500px|thumb|center|Mario Game FlowChart]]

=== Game work Flow Diagram ===
Task creation and managing tasks bandwidth was a crucial part of this project.
Update display is the core heart of display driver which does refreshing of LED screen matrix at a refresh rate of around 400 Hz.
Other tasks are of low priority which deals with various functionalities such as managing screen rotation, receiving Bluetooth data.

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen

Action: Joystick Button pressed
Switch over to Game UI

MARIO_Game_state : GAME_START_INITIATED

Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch over to the Game background screen

Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)

{

Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If Mario position collides with the Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from the beginning
If traversal pixel coordinate reaches victory coordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music

}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is fantastic resource for planning out levels ,background and designing characters of game .Images drawn using mtPaint can be convert into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Testing & Technical Challenges ==

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F21: ACE MARIO

2021-12-18T07:45:27Z

Proj user7:

[[File:13.jpg|right|500px|thumb|ACE MARIO GAME]]

== Abstract ==
Super Mario is one of the best-selling games of all time, with more than 50 million copies sold worldwide. Our goal will be to produce a similar version called ==Ace Mario== of it where the player controls Mario's movements. Mario has to race through hardships in form of obstacles and reach the mushroom kingdom which signifies the victory.

=== Objectives & Introduction ===

The main objective of this project was to create a Mario video game displayed on an RGB LED matrix. We used two SJ2 boards. One for graphics processing and, the other SJ2 board was used as a gamepad controller, which controller the graphics board and sends data to the LED matrix board.
Other objectives are as follows:

* Use the FreeRTOS Real-Time operating system on both the SJ2 boards.
* Interface the 64*64 RGB LED Matrix and MP3 decoder on one of the SJ2 boards.
* Interface Joystick, vibration sensor, Bluetooth on the other SJ2 board.
* Establish wireless communication between these two nodes using Bluetooth.
* Create and display characters on the LED matrix.
* Create different sound effects at different functions of the game.
* Create multiple display screens at different stages of the game.
* Integrate all the modules and develop smooth game logic.

'''How to Play ACE MARIO'''

The goal of the game is to descend forward in the right direction avoiding obstacles in the form of potholes and piranha plants and reach the Mushroom Kingdom which signifies the victory of the game.

*Using the joystick on the gamepad controller, we can control the movements of our Mario.
* a)To start the game press the joystick at the top.
* b)Mario can jump when the joystick is pressed in the upward direction and accordingly can ascend forward when pressed towards your right direction.
*As Mario ascends in the screen, the next background screen keeps appearing and we have to traverse until the game ends or we reach the mushroom kingdom.
*Avoid all the obstacles while ascending, by jumping over them.
*The entire game is time-based and lives-based i.e you need to reach the mushroom kingdom within the time span and you will be given 3 lives(heart-shaped).
*Last few seconds on your time span will be indicated by red battery lines, otherwise it will be green in color and is continuously diminishing the green lines as the game ascend.
*Failure to avoid obstacles as indicated by the game restart screen reduces your lives one by one. Hence, you will have only 3 chances to stay in the game with the usage of lives. Consequently, once you land on any obstacles and you have no lives left, the game ends.
*Having understand above, it's time to unleash the Ace Mario game now. Good Luck!
----

=== Team Members & Responsibilities ===
{| class="wikitable"
|-
! scope="col" style="background:#588ecc;"| '''Name''' 
! scope="col" style="background:#588ecc;"| '''Roles / Responsibilities'''
|-
! scope="row"|
[https://www.linkedin.com/in/tapkirvivek/ Vivek Tapkir]
|

*Game Logic Development
*Collision Detection
*Game state handling
*LED Matrix Driver
*Game animation implementation
*Software and Hardware Integration
*Bug fixes and performance improvement
|-
! scope="row"| Shreevats Gadhikar
|
*Game Logic Development
*Bluetooth and Joystick Driver
*Hardware Integration
*PCB Design
|-
! scope="row"| Daya Modekar
|
*MP3 Decoder Driver
*Game Logic Development
*Graphics Driver
*Hardware Integration
|}

== Schedule ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/15/2021
|
* 10/25/2021
|
* Read previous projects, gather information and discuss among the group members.
* Decide on 2 game ideas and submit Project Proposal assignment
* Discussion on using wireless or wired controllers,3D printing options,PCB softwares and manufacturer.
* Finalize parts list
* Create GitLab repository for project
* Decide on day/time for weekly meetings
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 2
|
*10/25/2021
|
*11/03/2021
|
*Choose game based on Preet's Project Proposal feedback
*Finish schedule rough draft and upload to Wiki report
*Order project parts
*Break project up into tasks and assign project tasks to team members
*Obtain datasheets for all parts and upload to team Google Drive folder
*Brainstorm gameplay, rules, and level design on paper
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed

|-
! scope="row"| 3
|
* 11/04/2020
|
* 11/08/2020
|
* Read and familiarize with LED Matrix Datasheet
* Read datasheets and conduct research for driver writing
* Finalize wiki schedule
* Test all parts to ensure proper functionality
* LED matrix can light a pixel(s) at specified locations.
* Finalize gameplay, rules, and level design on paper
* Start Developing graphics driver for LED matrix and implement initial game objects
* Begin developing MP3 decoder board driver
* Begin designing PCB in EasyEDA software
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 4
|
*11/09/2021
|
*11/15/2021
|

* Begin developing Bluetooth board driver
* LED matrix can display our game character and obstacles
* MP3 decoder can play/pause, jump to next/previous song, and increase/decrease volume
* Bluetooth modules can send controls data back and forth between gamepad board and master board
* Controls data can be accessed using "get" and "set" API
* Gamepad controller can read joystick and accelerometer values and detect switch presses
* Decide how to handle each collision detection case (character/enemy, obstacles/enemy, etc.)
* Finish enclosure design in AutoCAD software and start printing
* Finalize PCB design on paper and design in PCB software
* LED matrix displays character orientation correctly depending on current movement direction
* Controller input (joystick or accelerometer) option is implemented on a gamepad controller
* Finalize PCB design in software and order PCB
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
*LED matrix menu screens and game over/victory screens are implemented on matrix
*Volume controls and controller input select in the options menu are implemented
*Integrate circuitry with 3D printed enclosure
*PCB arrives, conduct PCB testing to ensure proper connections
*Solder PCB and integrate with existing project circuitry
*LED matrix can scroll to next screen when the character reaches the bottom of the current screen
*Finalize MP3 track selection for each screen and during gameplay
*Collision detection logic is fully functional and displays correctly on the LED matrix
* Testing and debugging the game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
* 11/23/2021

|
* 11/29/2021
|
* Integrate game logic code with LED matrix
* Write gameplay logic code on the master controller. Gameplay logic should update the score and status bar items correctly
* LED matrix graphics design for all levels is complete
* MP3 decoder plays correct song/track during gameplay and for each menu/game over screen
* Integrate game sounds with game logic
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/30/2021
|
* 12/06/2021
|
* Sub-system Integration
* Finish rough draft of project report
* Finalizing the video game
|
* Completed
* Completed
* Completed
|-
! scope="row"| 8
|
* 12/07/2021
|
* 12/13/2021
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed

|-
! scope="row"| 9
|
*12/14/2021
|
*12/16/2020
|
*Final Demo
*Update Gitlab repo with final code.
*Finalize project report and submit
|
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== Parts List & Cost ==
=== General Parts ===
{| class="wikitable"
|-
! scope="col"| Item #
! scope="col"| Part
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| 64x64 RGB LED Matrix
| [https://www.adafruit.com/product/3649 Adafruit]
| 1
| $54.95
|-
! scope="row"| 2
| SJ-2 Boards
| [https://www.amazon.com/Generic-SJTwo-SJ2-SJSU/dp/B08G9LRPZ8/ref=sr_1_4?dchild=1&keywords=sjsu+sj2+board&qid=1603064585&sr=8-4 SJSU]
| 2
| $100.00
|-
! scope="row"| 3
| HC-05 Bluetooth Boards
| [https://www.amazon.com/DSD-TECH-HC-05-Pass-through-Communication/dp/B01G9KSAF6/ref=sr_1_4?crid=1MTXACDA8RETK&keywords=hc-05&qid=1638426167&s=electronics&sprefix=HC-%2Celectronics%2C229&sr=1-4 Amazon]
| 2
| $20.00
|-
! scope="row"| 4
| MP3 Decoder/Player Board
| [https://www.amazon.com/HiLetgo-YX5300-Control-Serial-Arduino/dp/B0725RHR4D/ref=pd_sbs_1/140-3882465-6958023?pd_rd_w=zUdnA&pf_rd_p=690958f6-2825-419e-9c16-73ffd4055b65&pf_rd_r=6BQ384Y1GEKJ2HZQY723&pd_rd_r=61e015e0-d89a-47c1-9eaa-9a99f656ae36&pd_rd_wg=TuDjr&pd_rd_i=B0725RHR4D&psc=1 Amazon]
| 1
| $6.99
|-
! scope="row"| 5
| Joystick
| [https://www.amazon.com/HiLetgo-Controller-JoyStick-Breakout-Arduino/dp/B00P7QBGD2/ref=sr_1_1?keywords=Hiletgo+joystick&qid=1638426386&sr=8-1 Amazon]
| 1
| $4.89
|-
! scope="row"| 6
| Power Supply for LED Matrix (5V 5A)
| [https://www.amazon.com/ZOZO-Regulated-Switching-Replacement-Electronics/dp/B015PXUHYA/ref=sr_1_6?crid=1EJ10CN64YWS3&keywords=power+adapter&qid=1638426501&sprefix=power+adapt%2Caps%2C254&sr=8-6 Amazon]
| 1
| $15.99
|-
! scope="row"| 7
| JBL Speakers
| already had
| 1
| $0
|-
! scope="row"| 8
| Audio Jack Cable
| already had
| 1
| $0
|-
! scope="row"| 9
| MicroSD Card & Adapter
| already had
| 1
| $0
|-
! scope="row"| 10
| Vibration Sensor
| [https://www.amazon.com/dp/B07PVC7D5T/ref=cm_sw_r_apan_glt_fabc_P6A00CDDJ84Y6CBBSGG0 Amazon]
| 1
| $10.99
|-
|}

== Design & Implementation ==

=== Hardware Integration Design ===

For our project, we choose EasyEDA online software for designing the PCB. EasyEDA is completely free to use and all the footprints are easily available online. Also, EasyEDA has a feature of auto-routing which is very useful. The most important thing about EasyEDA is its ability to create a PCB from schematics.

[[File:LED Board.png|center|800px|thumb|LED Board PCB Schematic]]

[[File:Game pad board.png|center|800px|thumb|Game Board PCB Schematic]]

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Schematics.jpg|center|500px|thumb|Game Pad PCB (Front)]]
|
|[[File:Game board schematics.jpg|center|500px|thumb|Game Pad PCB (Back)]]
|
|}

We checked our schematics several times. We also manually checked the footprints for each part before ordering the PCB. We were succeeded in 1st attempt.

=== Fabrication ===

Using the EasyEDA we designed a 2 layer PCB. PCB was sent to fabrication to JLCPCB China which provided PCB within 7 days with MOQ of 5. The dimension of the 1st PCB was 8.5cm * 8 cm while the other was with the dimension of 16cm * 11.5cm. All the components were mounted as close to each other as possible to minimize the PCB dimensions.

PCB Properties:
Size: 8.5cm * 11.5cm and 16cm * 11.5cm 
Signal Layers: 2 
Componenets: 16 
Routing width: 0.254mm 
Track Width: 1mm 
Clearance: 0.3mm 
Via diameter: 0.61mm 
Via Drill Diameter: 0.31mm 
Vias: 20 

{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:LED Board PCB.jpeg|center|500px|thumb|LED Board Final PCB]]
|
|[[File:Game-pad controller.jpg|center|500px|thumb|Game pad controller]]
|
|}

----

=== LED Matrix ===

[[File:Mario Game flow.png|500px|thumb|center|Mario Game FlowChart]]

[[File:Codeflow.drawio.png|500px|thumb|center|Code flow ]]

[[File:Led matrix pin out.jpg|500px|thumb|center|Pinout for LED Matrix]]

'''Algorithm:'''

MARIO_Game_state: Initially START_GAME
Display Start screen
Action: Joystick Button pressed
Switch over to Game UI
MARIO_Game_state : GAME_START_INITIATED
Game Logic Task
Available lives = 3
Time starting from 0 counting towards 150 seconds
Mario on stationery position
Switch ove to Game backgroung screen
Start counting time within this routine till 150 seconds
if timer reached or Available lives ==0
: MARIO_Game_state -> GAME_OVER
Switch over to Game over Screen UI
If (MARIO_Game_state == GAME_START_INITIATED
&& Task tick count < 150 seconds
&& mario_available_lives !=0)
{
Action: Joystick forward command received
Rotate horizontal graphics matrix by x pixels
along with walking animation
Action: Joystick Jump command received
Rotate horizontal graphics matrix by 2x pixels
along with walking animation and music
Collision detection
If Mario position lies within Pothole
|| If mario position colides with Piranha plant
Mario dying animation and music
Available lives decremented by 1
Start game from beginning
If traversal pixel cordinate reaches victory cordinate
MARIO_Game_state = MARIO_VICTORY
Switch over to Victory Screen UI and victory music
}

----

=== MP3 Decoder ===
The MP3 player device which is based on a high-quality MP3 audio chip -YX5300 is used in our project to play different soundtracks based on the current state of the game such as jump, victory, game over and Mario run states. Our master controller unit (sjtwo-c board) controls MP3 playback state by sending commands to serial MP3 via UART port

[[File:MP3_module.JPG|300px|thumb|center|Serial MP3 Module]]
==== Hardware Design ====
The MCU controls the device playback by sending serial commands through a TTL level UART control interface (GND, VCC, TX, RX). Sound is output through a headphone jack to headphones or an external amplifier. The board has a playback indicator led that blinks during playback and is steady otherwise. The TF card socket on the PCB reverse is for plugging in the micro SD card with mp3/wav files. The micro SD card should be formatted as fat16 or fat32 and songs must be prefixed with a unique 3 digit index number (for example, 001xxx.mp3, 002xxx.mp3, 003xxx.mp3, etc, where xxx is an arbitrary optional name). The baud rate required for communication is 9600 bps. This decoder also contains an audio jack to connect headphones or speakers.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:Hw_design.JPG|500px|thumb|center|MP3 Hardware Interface]]
|[[File:Mp3_hw_map.JPG|500px|thumb|center|Hardware Support]]
|}

==== Software Design ====

The SJ2 board initializes UART for communicating to the MP3 decoder and allocates memory to load packet information before sending via TX line.Different song tracks were played depending on the game state for example victory song when the players wins, super Mario theme song else where.

In the project, we wait for an event, such as entering the title screen or game to start playing music.

[[File:MP3_flowchart.JPG|center|250px|thumb|MP3 Decoder flowchart]]

Below, are snippets of the code used to set up the commands and send them through UART. Before sending any other command, we must command the decoder to select device 2 (as described in the datasheet). A command we used in our ace Mario project was to play the song at index. The function that sends this command is called mp3_decoder__play_song_at_index(). Within commands, there are two function calls for setting up the packet (set_command_and_data()) and the other for sending the packet over UART (send_command_via_uart()) as shown below

<pre>
static void intialize_command_message(mp3_decoder__msg_t *mp3_decoder_message) {
mp3_decoder_message->mp3_decoder_command_byte.start_byte = cmd_start;
mp3_decoder_message->mp3_decoder_command_byte.version_byte = version;
mp3_decoder_message->mp3_decoder_command_byte.data_length = cmd_length;
mp3_decoder_message->mp3_decoder_command_byte.feedback_byte = no_feedback;
mp3_decoder_message->mp3_decoder_command_byte.end_byte = cmd_end;
}

static void set_command_and_data(uint8_t command, uint8_t data_0, uint8_t data_1) {
mp3_command_message.mp3_decoder_command_byte.command_byte = command;
mp3_command_message.mp3_decoder_command_byte.data_byte0 = data_0;
mp3_command_message.mp3_decoder_command_byte.data_byte1 = data_1;
}

static void send_command_via_uart(void) {
uint8_t i = 0;
while (i < 8) {
if (uart__polled_put(uart, mp3_command_message.mp3_decoder_command.bytes[i])) {
i++;
}
}
}

static void select_storage_device(void) {
static const uint8_t device = 0x02;
set_command_and_data(mp3_decoder__select_device, no_data, device);
send_command_via_uart();
}

void mp3_decoder__play_song_at_index(uint8_t index) {
set_command_and_data(mp3_decoder__play_at_index, no_data, index);
send_command_via_uart();
}
</pre>

=== Bluetooth Interface ===

For this project, we used two HC-05 Bluetooth modules. One Bluetooth was configured on the LED matrix controller board while the other was configured on the gamepad controller. The Bluetooth configured on the led matrix controller worked as a slave, only receives commands, while the one configured on the gamepad worked as master, sending controls to the other controller. The master Bluetooth connected to the gamepad controller transmitted the joystick direction. The transmitted direction was in the form of x and y coordinates. The UP and FORWARD direction was calibrated using the x and y coordinates. So along with UP and FORWARD direction, the joystick switch button data was also transmitted using Bluetooth.

We selected the HC-05 Bluetooth module to transmit data over other modules because of their ease to configure, they are extremely reliable and also easy to set up. Both the Bluetooth modules were configured using AT commands. Using AT commands made our job easy to set one Bluetooth as a master while the other as a slave. The best thing about using AT commands is that we can change the configuration as per our needs. The UART baud rate was set to 38400.

[[File:Bluetooth-HC 05.jpg|300px|thumb|center|HC-05 Bluetooth Module]]

==== Hardware Design ====

The HC-05 Bluetooth module was connected to both boards using the SJ2 pins. The pins used were P0.0 and P0.1. These Bluetooth modules communicate with each other over the UART interface. The gamepad controller board process the joystick signals to UP and FORWARD and also the button press and then sends them to the Bluetooth module via UART.

[[File:Bluetooth SJ2.jpg|500px|thumb|center|HC-05 Bluetooth Module to SJ2 Connections]]

==== Software Design ====

The following function "receive_from_bluetooth" was used to receive data from the Bluetooth.

void receive_from_bluetooth (void *p) {
char bluetooth_command_received[50];
bluetooth_command_received[0] = '\0';
while (1) {
char received_data = '\0';
if (uart__get(UART__3, &received_data, portMAX_DELAY)) {
strncat(bluetooth_command_received, &received_data, 1);
if (received_data == '\n') {
bluetooth__process_receive_data(bluetooth_command_received);
strcpy(bluetooth_command_received, "\0");
}
}
}
}

The following code snippet was used to process the received data. It simply compares the strings and, if the match is found the direction is set accordingly.

void bluetooth__process_receive_data(char string[]) {
if (strcmp(string, "CENTERED\r\n") == 0){
set_joystick_direction(CENTERED);
printf("CENTERED\n");
} else if (strcmp(string, "RIGHT\r\n") == 0){
set_joystick_direction(RIGHT);
printf("RIGHT\n");
} else if (strcmp(string, "JOYSTICK_ON\r\n") == 0) {
set_joystick_button_pressed(true);
printf("JOYSTICK_BUTTON\n");
}
}

=== Game pad Controller ===

Gamepad Controller basically consists of only three main components. Firstly the joystick, which is used to get the UP and FORWARD direction, and also the press button. Second is the Bluetooth module which is used to transmit the data via UART to the other board. And lastly, the vibration sensor to produce the vibration. The vibration sensor is used to get the real game feel.

[[File:Game pad controller.jpeg|400px|thumb|center|Game Pad Controller]]

=== Joystick ===

The joystick was interfaced on the Game-pad controller. We used a joystick to get a UP and FORWARD direction. The joystick was configured using ADC pins of the SJ2 board. The Joystick provides an analog output, therefore they were connected to ADC pins to get the digital values. The values of the X-axis and Y-axis varied from 0 to 4095. The center was 2048 for both X-axis and Y-axis. The UP and FORWARD direction was calculated using these ADC values. The joystick also had a digital switch. This digit switch was used as a press button in our game. These three contents (i.e UP, FORWARD, Button_press) were transmitted to the led board using Bluetooth.

[[File:Joystick-module.jpg|300px|thumb|center|Joystick Module]]

==== Hardware Design ====

The hardware design was pretty simple. The two analog output pins i.e X-axis and Y-axis were connected to ADC pins of the SJ2 board. The ADC pins used were P1.30 and P1.31 to get the UP direction and the FORWARD direction. The digital switch was connected to one of the gpio pins on the SJ2 board. This gpio pin was read to detect if the switch was pressed.

[[File:Joystick schematics.jpg|400px|thumb|center|Joystick Schematics]]

==== Software Design ====

This code snippet below demonstrates how we calculated the direction using the joystick. The joystick provides the analog values, so we used the ADC pins of the SJ2 board to get the digital values. The values range from 0 to 4095. According to these values threshold for UP and FORWARD/RIGHT were set.

static const int16_t UP_threshold = 500;
static const int16_t RIGHT_threshold = 3500;
joystick_direction_t joystick_controls__get_joystick_direction(void) {
joystick_direction_t joysticks_direction = CENTERED;
int joystick_pos_x = adc__get_channel_reading_with_burst_mode(X_axis);
int joystick_pos_y = adc__get_channel_reading_with_burst_mode(Y_axis);
if (joystick_pos_y < UP_threshold) {
joysticks_direction = UP;
printf("UP\n");
}
if (joystick_pos_x > RIGHT_threshold) {
joysticks_direction = RIGHT;
printf("RIGHT\n");
}
vTaskDelay(500);
return joysticks_direction;
}

=== Vibration Module ===

A vibration module was used to produce the vibration on the game-pad controller to get the real feel of the game. The vibration module was triggered on the Mario jump state and also when Mario died.

[[File:Vibration sensor.jpg|300px|thumb|center|Vibration module]]

==== Hardware Design ====

Vibration module consists of just 3 pins. VCC for power, Signal pin to trigger the pin, and GND. The signal pin of the vibration module was connected to one of the gpio pin (P0.29) of the SJ2 board.

[[File:Vibration sensor schematics.jpg|300px|thumb|center|Vibration module schematics]]

==== Software Design ====

A GPIO pin was used to signal the SIG pin of the vibration module.

gpio_s vibration_module_pin = {1, 29};

gpio__set(vibration_module_pin);
delay__ms(500);
gpio__reset(vibration_module_pin);

=== Game Graphics Implementation ===
The mtPaint software(open source) is fantastic resource for planning out levels ,background and designing characters of game .Images drawn using mtPaint can be convert into 2d-array representation using a python script or other image processing software. This is going to be much easier than writing entire screens out by hand and also saves time.
{| style="margin-left: auto; margin-right: auto; border: none;"
|[[File:MtPaint.JPG|500px|thumb|center| mtPaint Window...]]
|[[File:Python_Script.JPG|500px|thumb|center|Python Scripts]]
|}

== Testing & Technical Challenges ==

=== MP3 Decoder ===

* The datasheet lacks some information and clarity on module initialization and working. Initially, non of the commands appeared to work or have any effect. The issue was resolved after sending the command to select a device, which was not explicitly stated in the datasheet. Once this command is first sent, the MP3 decoder now begins accepting commands.
*The TF card folder structure for songs was unclear in the first go.

== Conclusion ==
Indeed, it was a great learning experience. It sharpened our driver writing skills as we coded each module we used (LED matrix, MP3 decoder, Bluetooth, etc.).We were able to learn a lot about a real-world projects such as FreeRTOS applications, drivers, PCB design, power management circuits, git source code management, and final integration testing. This project allowed us to understand the importance of writing down requirements, planning a schedule for development, and teamwork. Throughout the entire duration of this project, we encountered numerous challenges such as difficulty getting the LED matrix driver up and running, figuring out how to implement collision detection with so many game objects, hardware integration, and writing and maintaining our complex game logic state machine and much more. Despite the challenges and setbacks we faced, we were able to overcome every single one of them in order to build a finished product that we are all proud of.

=== Project Video ===

* [https://www.youtube.com/watch?v=zW5vmb5-Tc4 Demo Video Link]

=== Project Source Code ===

* [https://gitlab.com/Shreevats/mario-run Project source code]

=== Acknowledgement ===

We'd want to express our gratitude to our professor Preet and all of the ISAs for putting together such a fantastic class and for setting such high standards. This instilled in us the desire to go above and beyond.

=== References Used ===

----

LED Matrix

* [https://www.sparkfun.com/news/2650 Everything You Didn't Want to Know About RGB Matrix Panels]
* [https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/new-wiring AdaFruit LED Matrix Wiring]
Image Designing

* [http://mtpaint.sourceforge.net/ Mtpaint Source & Documentation]

MP3 Decoder

* [https://github.com/cefaloide/ArduinoSerialMP3Player MP3 Datasheets]
* [http://geekmatic.in.ua/pdf/Catalex_MP3_board.pdf Catalex_MP3_board_datasheet]

HC-05 Bluetooth Modules

* [https://howtomechatronics.com/tutorials/arduino/how-to-configure-pair-two-hc-05-bluetooth-module-master-slave-commands/ HC-05 Bluetooth Configuration & Pairing]
* [https://www.teachmemicro.com/hc-05-bluetooth-command-list/ HC-05 Bluetooth AT Commands]

PCB Designing

* [https://easyeda.com/ PCB Designing]
* [https://jlcpcb.com/ PCB fabrication]

F20: Bubble Shooter

2021-02-22T06:21:35Z

Proj user7: /* Bill Of Materials */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. The project focuses on integrating SJ2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
The micro-controller is integrated with peripheral drivers, led drivers, MP3 player, button, and joystick controller interface. The application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. A button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 2
| $100.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PCB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2021-02-17T21:31:16Z

Proj user7: /* MP3 Decoder */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. The project focuses on integrating SJ2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
The micro-controller is integrated with peripheral drivers, led drivers, MP3 player, button, and joystick controller interface. The application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. A button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PCB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:58:06Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. The project focuses on integrating SJ2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
The micro-controller is integrated with peripheral drivers, led drivers, MP3 player, button, and joystick controller interface. The application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. A button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:56:40Z

Proj user7: /* Joystick */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:56:18Z

Proj user7: /* LED Matrix */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:54:34Z

Proj user7: /* Software Design */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:53:48Z

Proj user7: /* LED Matrix */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

===LED Matrix Specifications===

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===
 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:53:09Z

Proj user7: /* LED Matrix */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===
 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:52:25Z

Proj user7: /* LED Matrix */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}
=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:51:39Z

Proj user7: /* Joystick */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:51:19Z

Proj user7: /* Hardware Design */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:50:44Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|Team Bubble Shooter|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V
2. Analog outputs
3. 1 mA draw when used with 5V
4. On-board button
5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:50:16Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V
2. Analog outputs
3. 1 mA draw when used with 5V
4. On-board button
5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:49:25Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V
2. Analog outputs
3. 1 mA draw when used with 5V
4. On-board button
5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:49:08Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right Team Bubble Shooter]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V
2. Analog outputs
3. 1 mA draw when used with 5V
4. On-board button
5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:48:47Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right] Team Bubble Shooter]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V
2. Analog outputs
3. 1 mA draw when used with 5V
4. On-board button
5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:48:20Z

Proj user7:

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V
2. Analog outputs
3. 1 mA draw when used with 5V
4. On-board button
5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral
2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.
3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).
4. Set the ADC pin functionality as input.
5. Select the number of channels to read.
6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}
data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and Sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.
2. Disable Output Enable (OE) GPIO before feeding matrix data.
3. Select the required row by setting bits on A, B, C, D GPIO pins.
4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.
5. Set zero on R, G, B GPIO pins to mask that particular pixel.
6. Set and Reset the clock for pushing the R, G, B bits for each column.
7. Issue latch to mark the row's completion and reset the latch before going to the next row.
8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {
game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;
draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:44:38Z

Proj user7:

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 
== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:43:17Z

Proj user7:

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:42:23Z

Proj user7:

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]\
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:41:13Z

Proj user7:

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]\
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:40:54Z

Proj user7:

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 
== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]\
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:39:32Z

Proj user7: /* References */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== '''References''' ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his all-round guidance, feedback, and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]\
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:36:51Z

Proj user7: /* Conclusion */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third-party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED. Once we could control LEDs one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lesson that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard, and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]\
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:36:30Z

Proj user7: /* References Used */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]\
* [https://www.youtube.com/watch?v=WW-VwLfq2aU&feature=youtu.be Joystick Reference]

F20: Bubble Shooter

2020-12-18T07:35:23Z

Proj user7: /* Schedule */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]

F20: Bubble Shooter

2020-12-18T07:33:32Z

Proj user7: /* Game Engine */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

The game starts with the Main Menu, which has the number of turns, score, and Level on the top. A credit count and Ball queue are placed at the bottom of the screen. Once the credit button is pressed and credits are accumulated and the game starts by pressing the trigger button. A bubble is ready inside the trigger and the player just needs to adjust the pointer and shoot in the desired direction. Two other bubbles based on the number of colored bubbles present on the top is available in the queue. After the ball is released from the trigger it checks the property of the above objects and functions accordingly. If the released bubble encounters a border wall, then it bounces off in the opposite direction, if it encounters the bubbles then sticks to it if it's a different color, else destroys all the same colored bubbles. And finally, if the ball touches the Wall on the top then it doesn't stick but gets destroyed. The trigger remains empty and the queue still has the old bubbles. Based on the final function of the released bubble, a function scans the number of different colored bubbles in the stack and calculates the color of bubbles that are present in more. The trigger and queue then get updated with new bubbles and the wall comes down a bit further near the danger line.

The above process keeps happening until either all the bubbles are cleared, the wall reaches the danger line, or you cheat your way to the next level. Have fun playing!

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]

F20: Bubble Shooter

2020-12-18T07:32:09Z

Proj user7: /* Objectives & Introduction */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a single-player 2D arcade game using LPC 4078 microcontroller on a 64 X 32 LED matrix display. Project focus on integrating Sj2 microcontroller board with LED Matrix, MP3 Decoder, 2 pushbuttons, and joystick.
It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]

F20: Bubble Shooter

2020-12-18T07:26:57Z

Proj user7: /* LED Matrix */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}

 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]

F20: Bubble Shooter

2020-12-18T07:25:26Z

Proj user7: /* References Used */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://learn.sparkfun.com/tutorials/rgb-panel-hookup-guide?_ga=2.111533508.177452041.1605078754-2035904423.1601235282 RGB Panel Hookup Guide 1]
* [https://www.mouser.com/datasheet/2/737/32x16-32x32-rgb-led-matrix-1396574.pdf RGB Panel Hookup Guide 2]
* [http://www.rayslogic.com/propeller/Programming/AdafruitRGB/MBI5026.pdf Shift Register Datasheet]
* [https://learn.sparkfun.com/tutorials/mp3-player-shield-hookup-guide-v15/all MP3 Decoder hookup guide]
* [https://datasheetspdf.com/pdf-file/640613/VLSI/VS1053B/1 VS1053B datasheet]

F20: Bubble Shooter

2020-12-18T07:21:26Z

Proj user7: /* Testing & Technical Challenges */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

=== Future Suggestions ===

1. Modify a single pixel with different locations to get a thorough understanding of the led matrix. Check all the possible colors to identify any faulty pixels on the board. Write a generic scalable code to help you in the game. Implement frame methodology to prevent flickering and achieve a smooth transition of pixels.

2. Preferably use UART based MP3 decoder rather than SPI.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:18:18Z

Proj user7: /* Feeding the Decoder and Playing Music */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:17:07Z

Proj user7: /* Conclusion */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== '''Conclusion''' ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:16:59Z

Proj user7: /* Bill Of Materials */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:16:50Z

Proj user7: /* Testing & Technical Challenges */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:16:49Z

Proj user7: /* Bill Of Materials */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|-
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99
|-
! scope="row"| 7
| Push Buttons
| [https://www.amazon.com/gp/product/B07SVSYDNM/ref=ppx_yo_dt_b_asin_title_o09_s00?ie=UTF8&psc=1 Push Buttons]
| 1
| $7.99
|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble. == '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:15:54Z

Proj user7: /* Testing & Technical Challenges */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99

|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble. == '''Testing & Technical Challenges''' ==
As with any other project, even this threw challenges along the way.

=== LED Matrix ===
1. Understanding the matrix and then getting it to run was difficult as proper documentation or resource for the matrix was not available.

2. OE pin was not active low and it took us some time to figure it out.

3. Bubble, after released by the player, should move in the direction of the pointer and bounce off the border wall.

A graphics library was developed to print Alphanumerics in both horizontal and vertical positions. The driver was designed in a way to simply accept the coordinates of the board, shape, and color of the bubble instead of plotting it manually.

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:15:41Z

Proj user7: /* Bill Of Materials */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
! scope="row"| 6
| PAM8403 Amplifier and Speaker
| [https://www.amazon.com/gp/product/B07CRVRG83/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 Amplifier and Speaker]
| 1
| $11.99

|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
1. RGB LED Matrix Display driver

a) Setting up the LED Matrix was a bit of a challenge. Started with glowing a single row and column. Getting the initial hold on the exact row and column position was a bit tricky as one can easily get confuse on the starting and ending row and column. Once we got over it we moved on to design game objects separately.

b) Flickering of led matrix was solved by doing the following:

The frequency of refreshing the led matrix was increased to show smooth transition from one frame to another.
Led matrix is very sensitive to the inputs provided to it. Initially the flickering was thought to be because of the data lines and row selection lines. But later with further diagnoses it was discovered that the power supply line was creating issues. Changing the adapter eliminated the flickering.

2. Designing the MP3 Decoder

a) Earlier we used the ssp2 Driver written by Preet for SPI interfacing to write the data to MP3 Decoder. but somehow we were not able to detect the slave properly because of which we could not communicate with the decoder.

Resolution : We wrote our own simple SPI driver which sends the data to the MP3 Decoder for playing the music in background.
b) While reading data from the SD Card sometimes we faced few issues like hardware error occured in disk i/o and physical drive cannot work.

Resolution : The default driver was using mount later option for SD Card we changed it to mount immediately and the issue got resolved.

3. Integration Issues

a) Game logic was developed independently

Careful time and consideration had to be taken to ensure that the APIs were able to be stitched together. This actually ended up going smoother than we had anticipated. The Inter-board communication driver was designed to handle almost everything regarding the controllers, providing very abstract and simple APIs. This allowed for relatively smooth integration.

b) After game and controller logic, the main SJ2 did not have enough processing power to adequately driver the music functionality.

A standalone SJ2 board was used for the game soundtrack. This eased the load on our main board which was starting to effect our gameplay

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:14:49Z

Proj user7: /* Testing & Technical Challenges */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
1. RGB LED Matrix Display driver

a) Setting up the LED Matrix was a bit of a challenge. Started with glowing a single row and column. Getting the initial hold on the exact row and column position was a bit tricky as one can easily get confuse on the starting and ending row and column. Once we got over it we moved on to design game objects separately.

b) Flickering of led matrix was solved by doing the following:

The frequency of refreshing the led matrix was increased to show smooth transition from one frame to another.
Led matrix is very sensitive to the inputs provided to it. Initially the flickering was thought to be because of the data lines and row selection lines. But later with further diagnoses it was discovered that the power supply line was creating issues. Changing the adapter eliminated the flickering.

2. Designing the MP3 Decoder

a) Earlier we used the ssp2 Driver written by Preet for SPI interfacing to write the data to MP3 Decoder. but somehow we were not able to detect the slave properly because of which we could not communicate with the decoder.

Resolution : We wrote our own simple SPI driver which sends the data to the MP3 Decoder for playing the music in background.
b) While reading data from the SD Card sometimes we faced few issues like hardware error occured in disk i/o and physical drive cannot work.

Resolution : The default driver was using mount later option for SD Card we changed it to mount immediately and the issue got resolved.

3. Integration Issues

a) Game logic was developed independently

Careful time and consideration had to be taken to ensure that the APIs were able to be stitched together. This actually ended up going smoother than we had anticipated. The Inter-board communication driver was designed to handle almost everything regarding the controllers, providing very abstract and simple APIs. This allowed for relatively smooth integration.

b) After game and controller logic, the main SJ2 did not have enough processing power to adequately driver the music functionality.

A standalone SJ2 board was used for the game soundtrack. This eased the load on our main board which was starting to effect our gameplay

=== MP3 Decoder ===
1. Communicating with the decoder using SSP was challenging and took multiple rounds of debugging to start playing the tracks.

2. Switching between the songs when levels change also gave some issues.

Inputs from SJ2 were enabled to indicate the level change within the state machine, this way when the level changed the respective pin indicated the song to be played.

=== Game Design ===
1. First major challenge was to clear all the same colored bubbles once it was hit by the player bubble.

2. The Second challenge was to figure out an algorithm for the released bubble to either get attached or destroyed when it touches the bubble-block.

3. Designing the functionalities of border walls to bounce the released bubble, the wall to come down and destroy if the player bubble touches it, and aligning with nearby bubbles were few other challenges faced in game design.

A function that scans the bubble-block and then returns the number of different colored bubbles present was implemented to identify and destroy all the same colored bubbles. Bubbles were defined with sticky and player properties and when the player bubble encounters the sticky property, stops moving and either sticks to it or destroys it. Similarly, a wall and bounce property was defined to guide the bubble.

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:12:42Z

Proj user7: /* Schedule */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* Completed
* Completed
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
1. RGB LED Matrix Display driver

a) Setting up the LED Matrix was a bit of a challenge. Started with glowing a single row and column. Getting the initial hold on the exact row and column position was a bit tricky as one can easily get confuse on the starting and ending row and column. Once we got over it we moved on to design game objects separately.

b) Flickering of led matrix was solved by doing the following:

The frequency of refreshing the led matrix was increased to show smooth transition from one frame to another.
Led matrix is very sensitive to the inputs provided to it. Initially the flickering was thought to be because of the data lines and row selection lines. But later with further diagnoses it was discovered that the power supply line was creating issues. Changing the adapter eliminated the flickering.

2. Designing the MP3 Decoder

a) Earlier we used the ssp2 Driver written by Preet for SPI interfacing to write the data to MP3 Decoder. but somehow we were not able to detect the slave properly because of which we could not communicate with the decoder.

Resolution : We wrote our own simple SPI driver which sends the data to the MP3 Decoder for playing the music in background.
b) While reading data from the SD Card sometimes we faced few issues like hardware error occured in disk i/o and physical drive cannot work.

Resolution : The default driver was using mount later option for SD Card we changed it to mount immediately and the issue got resolved.

3. Integration Issues

a) Game logic was developed independently

Careful time and consideration had to be taken to ensure that the APIs were able to be stitched together. This actually ended up going smoother than we had anticipated. The Inter-board communication driver was designed to handle almost everything regarding the controllers, providing very abstract and simple APIs. This allowed for relatively smooth integration.

b) After game and controller logic, the main SJ2 did not have enough processing power to adequately driver the music functionality.

A standalone SJ2 board was used for the game soundtrack. This eased the load on our main board which was starting to effect our gameplay

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]

F20: Bubble Shooter

2020-12-18T07:12:00Z

Proj user7: /* Technical Responsibilities */

== '''Abstract''' ==
Bubble shooter is an arcade game that has bubbles or balls present on the screen. The bubbles are of different colors and the goal is to clear them by forming a group of bubbles (3 or more) of the same color. Points are earned upon clearing the bubbles and increases with the number of bubbles cleared in a single shot. The player wins upon clearing the screen and loses when the bubbles touch the bottom of the screen.

[[File:Abstract_Bubble_Shooter.png|800px|thumb|center|Block Diagram of Bubble Shooter]]

== '''Objectives & Introduction''' ==
[[File:Project Pic.jpg|thumb|500x500px|right]]

The objective of this project is to develop a simple, single-player 2D game using LPC 4078 microcontroller on an LED matrix display. It focuses on integrating the micro-controller peripheral drivers, led drivers, MP3 player, button and joystick controller interface and the application software in FreeRTOS. The button controller interface consists of the joystick for moving the shooter left and right. The button is used to fire the ball.

=== Team Members ===
* '''''[https://www.linkedin.com/in/akshat-bhutiani-048235119/ Akshat Bhutiani]'''''
* '''''[https://www.linkedin.com/in/amirajnigam/ Amiraj Nigam]'''''
* '''''[https://www.linkedin.com/in/anirudh-ashrit/ Anirudh Ashrit]'''''
* '''''[https://www.linkedin.com/in/hisaam-hashim/ Hisaam Hashim]'''''

== '''Technical Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Game Logic Development
| Hisaam Hashim, Amiraj Nigam, Anirudh Ashrit, Akshat Bhutiani
|-
! style="text-align: left;" |
* PCB Design
| Anirudh Ashrit
|-
! style="text-align: left;" |
* LED and Graphics Display Driver
| Hisaam Hashim
|-
|-
! style="text-align: left;" |
* Mp3 Decoder Driver
| Amiraj Nigam
|-
! style="text-align: left;" |
* Joystick Integration
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Hardware Integration
| Amiraj Nigam, Anirudh Ashrit, Hisaam Hashim
|-
|}

== '''Administrative Responsibilities''' ==

{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|- style="vertical-align: top;"
|-
! style="text-align: left;" |
* Team Leader
| Hisaam Hashim
|-
! style="text-align: left;" |
* Git Repository Managers
| Akshat Bhutiani
|-
! style="text-align: left;" |
* Code Reviewer
| Hisaam Hashim
|-
! style="text-align: left;" |
* Wiki Report Managers
| Amiraj Nigam & Anirudh Ashrit
|-
! style="text-align: left;" |
* Bill of Materials Manager
| Amiraj Nigam
|-
|}
 

== '''Schedule''' ==

{| class="wikitable"
|-
! scope="col"| Week#
! scope="col"| Start Date
! scope="col"| End Date
! scope="col"| Task
! scope="col"| Status
|-
! scope="row"| 1
|
* 10/12/2020
* 10/16/2020
|
* 10/18/2020
* 10/18/2020
|
* Literature Survey of Previous year Projects
* Submission of Project Proposal
|
* Completed
* Completed
|-
! scope="row"| 2
|
*10/18/2020
|
*10/20/2020
|

*Gitlab Repository Created
*Wiki Schedule page Created
|
* Completed
* Completed
|-
! scope="row"| 3
|
*10/20/2020
|
*11/01/2020
|
*Read and familiarize with LED Matrix Datasheet.
*Finalize the Components and place the order
|
* Completed
* Completed
|-
! scope="row"| 4
|
* 11/01/2020
|
* 11/10/2020
|
* Understand the ball tracing logic
* Understand the logic for ball queue
|
* Completed
* Completed
|-
! scope="row"| 5
|
*11/09/2020
*11/09/2020
*11/09/2020
*11/09/2020
|
*11/10/2020
*11/15/2020
*11/15/2020
*11/15/2020
|
* Finalize wiki schedule
* LED Matrix Driver Development
* MP3 Decoder Driver Development
* Joystick driver development and interfacing
* Game logic development
|
* Completed
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 6
|
*11/16/2020
|
*11/22/2020
|
*Designing of levels in the game
*Testing trigger motions
*Testing and debugging the game logic
*PCB Designing
|
* Completed
* Completed
* Completed
* Completed
|-
! scope="row"| 7
|
* 11/23/2020

|
* 11/29/2020
|
* Integrate game logic code with LED matrix
* Integrate game sounds with game logic
|
* Completed
* Completed
|-
! scope="row"| 8
|
* 11/30/2020
|
* 12/06/2020
|

* Integrate subsystem
* Finalizing the video game
* Update the wiki page.
|
* Completed
* Completed
* Completed
|-
! scope="row"| 9
|
* 12/07/2020
|
* 12/13/2020
|
* Address bugs during testing of an integrated system
* Test pause/play functionality
|
* Completed
* Completed
|-
! scope="row"| 10
|
*12/16/2020
*12/14/2020
*12/14/2020
*12/14/2020
|
*12/16/2020
*12/16/2020
*12/16/2020
*12/16/2020
|

*Final Demo
*Update Gitlab repo with final code.
*Update test video.
*Update the wiki page.
|
* Completed
* Completed
* In progress
* in progress
|-
|}

<HR>
 

== '''Bill Of Materials''' ==
{| class="wikitable" style="margin-left: 0px; margin-right: auto;"
|-
! scope="col"| Item#
! scope="col"| Part Description
! scope="col"| Part Model & Vendor
! scope="col"| Quantity
! scope="col"| Cost
|-
! scope="row"| 1
| Microcontroller Boards
| SJ2 Boards (Purchased from Preet Kang)
| 1
| $50.00
|-
! scope="row"| 2
| LED Matrix Display
| [https://www.amazon.com/dp/B07D4QF1JQ/ref=cm_sw_r_wa_apa_i_jCHMFbJEVVVQ8?_encoding=UTF8&psc=1 RGB LED Matrix Panel - 32X64]
| 1
| $55.00
|-
! scope="row"| 3
| Audio decoder Breakout Board
| [https://www.sparkfun.com/products/12660 MP3 PLayer Shield]
| 1
| $26.95
|-
! scope="row"| 4
| Analog 2-axis Thumb Joystick
| [https://www.amazon.com/Adafruit-Analog-2-axis-Joystick-Breakout/dp/B00NAY2Q6O Analog 2-axis Joystick]
| 1
| $10.36
|-
! scope="row"| 5
| Power Supply
| [https://www.amazon.com/inShareplus-Voltage-Transformer-100-240V-Connector/dp/B01GCI9G4O/ref=sr_1_1_sspa?dchild=1&keywords=5v%2Bpower%2Bsupply&qid=1604997761&sr=8-1-spons&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUEzUk1FVEpQWTFYUFBGJmVuY3J5cHRlZElkPUEwOTQ2MjkzMVE3UTZIMTdTVlpGNyZlbmNyeXB0ZWRBZElkPUEwNjkwMzM5MkZPNUtPOEJVNDJMWiZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU&th=1 5V/3A Power Supply]
| 1
| $8.99
|}

<HR>
 

== '''PCB Design''' ==
The board is designed to connect modules in the game directly. Autodesk's Eagle software is used to design the Schematics and Board layout. The board has 2 layers(Top and Bottom). JLCPCB is the manufacturer of the PCB board. Connections from SJ2 Board are provided to the PCB, which are internally connected to MP3 Decoder, Joystick, Buttons, and LED Matrix pins. These are connected directly to the peripherals using a harness. Additional power and ground pins are also provided on the board.
* [https://www.youtube.com/watch?v=1AXwjZoyNno AutoDesk Eagle Software Tutorial]

[[File:PCB_Schematic_BS.png|500x600px|thumb|left|Schematic Design of PCB]]
{|
|[[File:PCB_Board_Overview.png|500x600px|thumb|center|Design Overview of the PCB]]
|[[File:PCB_front.png|500x600px|thumb|right|PCB Board Layout]]
|}
{|
|[[File:PCB_Bubble_Shooter_Front.jpg|500x600px|thumb|left|PCB Front Face]]
|[[File:PCB_Bubble_Shooter_Back.jpg|500x600px|thumb|center|PCB Back Face]]
|}

== '''Joystick'''==

=== Hardware Design ===
An ADA512 2-axis Analog Joystick and Button is used for controlling the movement of the launcher and shooting the ball. The data from the joystick is read using the ADC pins of the SJTwo board. The button switch is detected using a digital pin on the board.

Features of the joystick:

1. Usable with any voltage up to 5V

2. Analog outputs

3. 1 mA draw when used with 5V

4. On-board button

5. High sensitivity

{|
[[File:Break out board.jpg|500x280px |thumb|left|Breakout board layout]]
|[[File:.Soldered and working.jpg|500x280px |thumb|center|Soldered joystick]]
|}

===Software Design & Implementation===
The ADA512 joystick's device driver works on the principle that the ADC pins will be able to read the x and y values. The joystick consists of 2 inbuilt potentiometers that provide output (x and y directions) according to the way the joystick is moved.

{| class="wikitable"
|-
! scope="col"| X values & Mapping
! scope="col"| Y values & Mapping
|-
! scope="row"| 2297 (center)
! scope="col" | 2295 (center)
|-
|-
! scope="row"| 43 (left)
! scope="col" | 45 (up)
|-
|-
! scope="row"| 4095 (right)
! scope="col" | 4090 (down)
|-
|}

 '''Steps to read joystick data:''' 

1. Turn on the ADC Peripheral

2. Make the ADC pin operational by setting the appropriate pin functionality using the IOCON registers.

3. Set the appropriate ADC clock (12.4 MHz is the maximum clock supported by the ADC).

4. Set the ADC pin functionality as input.

5. Select the number of channels to read.

6. Select burst mode for immediate conversion.

void adc__initialize_alien(void)
{
Turn ON ADC peripheral;
make ADC operational;
set ADC clock;
Set Pin functions;
select ADC channels;
start burst mode;
}

data get_data(adc_channel_e x_port, adc_channel_e y_port, gpio_s button_press) {
data s;
s.x_data = adc__get_adc_value(x_port);
s.y_data = adc__get_adc_value(y_port);
if (gpio__get(button_press)) {
s.switch_pressed = true;
} else {
s.switch_pressed = false;
}
return s;
}

== '''MP3 Decoder''' ==

The MP3 shield communicates with the sister SJ2 board through SPI communication protocol with the SPI0 pins of the SJ2 board as follows:

{| class="wikitable"
|-
! scope="col"| Label
! scope="col"| Name
! scope="col"| Function
! scope="col"| Pin Connection
! scope="col"| Description
|-
! scope="row"| 1
| MP3-DREQ
| Decoder Data Request
| Pin 0.1
| MP3 decoder signals to master to ready to receive next 32 bytes of data
|-
! scope="row"| 2
| MP3-CS
| VS1053B Chip Select
| Pin 0.22
| Chip select pin for MP3 decoder to be activated while sending control signals
|-
! scope="row"| 3
| MP3-DCS
| VS1053B Data CS
| Pin 0.0
| Data Chip Select Pin for the MP3 decoder to be activated while sending audio data signals.
|-
! scope="row"| 4
| MP3-RST
| VS1053 Reset
| Pin 0.10
| Reset pin for the MP3 Decoder
|-
! scope="row"| 5
| MOSI
| Master Output Slave Input
| Pin 0.18
| Master send data to Slave over SPI bus
|-
! scope="row"| 6
| MISO
| SPI Bus (Master Input Slave Output)
| Pin 0.17
| Slave send data to master over SPI bus
|-
! scope="row"| 7
| SCK
| SPI Clock
| Pin 0.15
| Clock generated by the master over SPI bus
|-
! scope="row"| 8
| +5V
| +5V
| PCB Vout
| 5 Volt Input from PVB
|-
! scope="row"| 9
| GND
| GND
| GND
| GND connected to PCB
|}

===Hardware Design===

[[File:MP3 Layout.png|800x1200px|thumb|center|MP3 Layout]]

===Software Design===

[[File:MP3 Flow Chart(1).png|700x800px|thumb|center|MP3 Layout]]

===Implementation===
To initialize the MP3 decoder, we have first initialized the SSP0 and the SJ2 pins connected to the MP3 decoder with proper input/output function configurations. We then configure the decoder registers by selecting the MP3 chip select pin and writing data over SPI. These include the mode (default), clock frequency multiplier (3x), volume (max), and audio (44100 Hz stereo data). We then flush the mp3 decoder, sending it 2500 0 bytes.
Reading the MP3 File from an SD Card[edit]
We create a low priority task (read_song_from_sd_card) to read from the SD Card. Read_song_from_sd_card task first opens the mp3 file on the sd card and determines the size. Afterward, it reads in 512 bytes at a time to a global array (whenever the music playing task has finished playing the previous 16 bytes) and sets a global variable (sdready) to true. It will continue to do this until the file has been completely read, and then start over from the beginning.

===Feeding the Decoder and Playing Music===
We create another low priority task (play_song_task) to play music. If the MP3 DREQ pin is currently set, it delays. Otherwise, whenever sdready is true, it selects the Data chip select line and sends 32 bytes over the SPI bus. It then deselects data chip select and redoes this 16 times (sending the 512 bytes that have been read). After it has sent all 512 bytes, it sets sdready to false so the read_song_from_sd_card task knows to read in the next 512 bytes. It continues to repeat this process for as long as mp3sdcard reads in data to the array.

//Task to read song from sd card
void read_level_1_bgm_from_sdcard(void *p) {
vTaskSuspend(NULL);
unsigned int ptr_to_bytes_read = 0;
while (1) {
const char filename_path[] = "level1.mp3";
FIL song;
// Open or creates a file
FRESULT check = f_open(&song, filename_path, (FA_READ | FA_OPEN_ALWAYS));
if (FR_OK == check) {
f_lseek(&song, f_size(&song));
current_position_in_mp3_file = f_tell(&song);
current_position_in_mp3_file /= 32;
f_lseek(&song, 0);
mp3_file_size = 0;
song_position = 0;
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
while (mp3_file_size < current_position_in_mp3_file + 32) {
if (song_position == 16 & sdready == false || sdready == false) {
f_read(&song, &data_buffer, BYTES_TO_READ, &ptr_to_bytes_read);
mp3_file_size += 16;
song_position = 0;
sdready = true;
}
vTaskDelay(1);
}
printf("Song finished! \n");
f_close(&song);
song_position = 0;
mp3_file_size = 0;
vTaskDelay(500);
}
else {
printf("Failed to read SD card \n");
}
vTaskDelay(1);
}
}

//Task to play song
void play_song_task(void *p) {
vTaskSuspend(NULL);
while (mp3_file_size < current_position_in_mp3_file + 32) {
while ((song_position < 16) && (sdready == true) && (mp3_sel == 0)) {
while (!(LPC_GPIO0->PIN & (MP3_DREQ))) {
vTaskDelay(1);
;
}
LPC_GPIO0->CLR = (MP3_DCS);
for (int a = 0; a < 32; a++) {
spi0_ExchangeByte(data_buffer[a + (song_position * 32)]);
}
// sdready = false;
song_position++;
LPC_GPIO0->SET = (MP3_DCS);
if (song_position == 16) {
mp3_sel = 0;
sdready = false;
}
}
}
}

===Binary Semaphore===
We have low priority created check_which_song_recieved_from_main_sj2_board_semaphore_give which will act as a producer task which will select which mp3 background music or sound fx need to be played and it will give the semaphore of the selected music file to the high priority consumer task called play_song_task which will suspend all other song handlers and play the selected song.

===Communication between Main and sister SJ2 board===
We have initialized 3 GPIO pins on the main(P0.15, P0.18, P0.1) and sister board(P2.0, P2.2, P2.5) and we have a total of 8 songs list, to which the respective GPIO pins will be high or low based on the song selection. The GPIO pins on the mainboard will be the output pins and the GPIO pins on the sister board will be the input pins. Henceforth, the sister board will receive input from the mainboard for the song selection and a binary semaphore will play the song.

== '''LED Matrix''' ==

=== Hardware Design ===

We use a 32x64 LED matrix consisting of 2048 LEDs arranged in 32 rows and 64 columns each, with each led having separate Red, Green, and Blue LED chips assembled together as a single unit. This 32x64 LED matrix is comprised of 2 of 16x32 led matrices placed vertically to each other. There are different drivers for controlling the corresponding rows and columns each. In order to illuminate a particular led, one needs to access and control the corresponding row and column (just like the coordinate-axis). To change the color of a particular led, each led must be controlled using the driver for that row and column. A layout of pins and connections can be seen below:

[[File:LED_Bubble_Shooter_Pin_Layout.png|800x300px |thumb|left|LED Matrix and SJ2 Connections]]
[[File:LED_Ribbon.png|800x300px |thumb|right|LED Matrix Ribbon Connector]]
{| class="wikitable"
|-
! scope="col"| LED Matrix Pins
! scope="col"| Connection to SJTwo board
|-
! scope="col"| R0
! scope="col"| Pin 0.1
|-
! scope="col"| G0
! scope="col"| Pin 1.1
|-
! scope="col"| B0
! scope="col"| Pin 1.4
|-
! scope="col"| R1
! scope="col"| Pin 4.28
|-
! scope="col"| B1
! scope="col"| Pin 0.6
|-
! scope="col"| G1
! scope="col"| Pin 0.8
|-
! scope="col"| A
! scope="col"| Pin 1.23
|-
! scope="col"| B
! scope="col"| Pin 1.29
|-
! scope="col"| C
! scope="col"| Pin 2.1
|-
! scope="col"| D
! scope="col"| Pin 2.4
|-
! scope="col"| CLK
! scope="col"| Pin 0.26
|-
! scope="col"| STB
! scope="col"| Pin 1.31
|-
! scope="col"| OE
! scope="col"| Pin 1.20
|-
! scope="col"| GND
! scope="col"| GND
|-
|}
<HR>
 

The matrix pixels are controlled by 6 drivers, 3 for the top half of the matrix(R0, G0, B0) and 3 for the bottom half(R1, G1, B1). The three drivers for R, G, and B share an SCLK, Latch, and OE signal. The top half pixels of the matrix controlled by R0, G0, B0 are rows 0-15, and the second half controlled by R1, G1, B1 are rows 16-31. The display is multiplexed at a duty cycle of 1/16, this means that one row in the top half and one row in the bottom half will be illuminated at a time. In order to display an image, the row and column LEDs for that image must be turned “ON”, therefore, the entire panel must be scanned at a rate(speed) at which it appears that the image is being displayed without flickering. To display different colors and different brightness levels, the LED chips of the corresponding row and column must be adjusted by varying the amount and time that each LED chip is turned on during each cycle.

'''LED Matrix Specifications:'''

5V regulated power input, 4A max (all LEDs on)

2.1 mm x 2.1 mm LED size

1/16 Scan Rate

{|
[[File:LED Matrix Schematic.png|800x300px |thumb|left|LED Matrix Interfacing]]
|[[File:LED Bubble Shooter.png|800x300px |thumb|center|Start Screen of the game]]
|}

=== Software Design ===

 '''Game''' 

The game has 3 levels apart from the main menu, Credit scene, and Game-over screen. Just like any other arcade game, the game only starts when you earn credits and it is earned by pressing a button. The game begins with the press of another button. A block of bubbles starts falling down with every turn and finishes if it touches the danger line below. Bubbles, when hit with similar color, get destroyed and the game advances to the next level when all the bubbles on the screen are cleared. There's also a hack to traverse through levels, just press the credit score button and it will do the job for you. But hey, that's a cheat code, so you're a cheater!

'''RGB Color Combo'''
{| class="wikitable"
|-
! scope="col"| Red
! scope="col"| Blue
! scope="col"| Green
! scope="col"| Color
|-
! scope="row"| 0
| 0
| 0
| White
|-
! scope="row"| 0
| 0
| 1
| Blue
|-
! scope="row"| 0
| 1
| 0
| Green
|-
! scope="row"| 0
| 1
| 1
| Cyan
|-
! scope="row"| 1
| 0
| 0
| Red
|-
! scope="row"| 1
| 0
| 1
| Magenta
|-
! scope="row"| 1
| 1
| 0
| Yellow
|-
! scope="row"| 1
| 1
| 1
| Black
|}

 '''Implementation''' 

1. Initialize the LED matrix by configuring necessary pin directions.

2. Disable Output Enable (OE) GPIO before feeding matrix data.

3. Select the required row by setting bits on A, B, C, D GPIO pins.

4. Loop through the pixels (columns) in the selected row and set the pixel color on R, G, B GPIO pins.

5. Set zero on R, G, B GPIO pins to mask that particular pixel.

6. Set and Reset the clock for pushing the R, G, B bits for each column.

7. Issue latch to mark the row's completion and reset the latch before going to the next row.

8. Follow steps 2 to 7 for other rows.

for (uint8_t row = 0; row < (MAX_ROW); row++) {
disableOE();
set_row(row);
for (uint8_t col = 0; col < MAX_COL; col++) {
LPC_GPIO0->PIN |= (1 << CLK);
set_color_bottom(game_matrix[row + (MAX_ROW / 2)][col]);
set_color_top(game_matrix[row][col]);
LPC_GPIO0->PIN &= ~(1 << CLK);
}
LPC_GPIO0->PIN |= (1 << LAT);
enableOE();
LPC_GPIO0->PIN &= ~(1 << LAT);
enableOE();
vTaskDelay(1);
}

=== Graphics Driver ===
We have managed to program the graphics in a relatively simple way by looking at the ADAFruit gfx library that comes ready to use with Arduino. Our graphics driver can implement graphics and animations such as letters, numbers, ball appearance and ball disappearance etc.

void place_launcher(LedMatrixDisplay led_display, pixel_color rgb, gfx__cursor start_cursor, bool
choose_back_frame) {

game_event object_property = BACKGROUND_OBJECT;
rgb.event = object_property;

draw_line(led_display, rgb, ROTATION_90, start_cursor, 9, choose_back_frame);

modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 0, start_cursor.y + 2, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 1, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 2, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 3, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 4, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 5, start_cursor.y + 5, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 6, start_cursor.y + 4, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 7, start_cursor.y + 3, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 1, choose_back_frame);
modify_pixel(led_display, rgb, start_cursor.x + 8, start_cursor.y + 2, choose_back_frame);
}

{|
[[File:level.jpg|500x300px |thumb|left|Game Level 1]]
|[[File:gameover.png|500x300px |thumb|right|Game Over Screen]]
|[[File:graphics.jpg|400x200px |thumb|center|Graphics display]]
|}

== '''Game Engine''' ==
[[File:game logic.jpeg|1000x1000px|thumb|center|Game Design]]

== '''Testing & Technical Challenges''' ==
1. RGB LED Matrix Display driver

a) Setting up the LED Matrix was a bit of a challenge. Started with glowing a single row and column. Getting the initial hold on the exact row and column position was a bit tricky as one can easily get confuse on the starting and ending row and column. Once we got over it we moved on to design game objects separately.

b) Flickering of led matrix was solved by doing the following:

The frequency of refreshing the led matrix was increased to show smooth transition from one frame to another.
Led matrix is very sensitive to the inputs provided to it. Initially the flickering was thought to be because of the data lines and row selection lines. But later with further diagnoses it was discovered that the power supply line was creating issues. Changing the adapter eliminated the flickering.

2. Designing the MP3 Decoder

a) Earlier we used the ssp2 Driver written by Preet for SPI interfacing to write the data to MP3 Decoder. but somehow we were not able to detect the slave properly because of which we could not communicate with the decoder.

Resolution : We wrote our own simple SPI driver which sends the data to the MP3 Decoder for playing the music in background.
b) While reading data from the SD Card sometimes we faced few issues like hardware error occured in disk i/o and physical drive cannot work.

Resolution : The default driver was using mount later option for SD Card we changed it to mount immediately and the issue got resolved.

3. Integration Issues

a) Game logic was developed independently

Careful time and consideration had to be taken to ensure that the APIs were able to be stitched together. This actually ended up going smoother than we had anticipated. The Inter-board communication driver was designed to handle almost everything regarding the controllers, providing very abstract and simple APIs. This allowed for relatively smooth integration.

b) After game and controller logic, the main SJ2 did not have enough processing power to adequately driver the music functionality.

A standalone SJ2 board was used for the game soundtrack. This eased the load on our main board which was starting to effect our gameplay

== Conclusion ==
This project was a fun and strenuous application of our engineering and project management skills.

After completing the driver labs during CMPE 244, we felt confident that we could develop a driver, for the Adafruit LED matrix, without using any third party libraries. We researched the hardware operations of the LED matrix and how to drive the RGB LED's. Once we could control LED's one at a time, the project evolved from an engineering problem into more of a creative exercise.

Overall I think the biggest lessons that we learned is project management based. We spent a lot of time choosing between various game designs and it forced us to start our final iteration later than we would have liked. However, we bonded together and worked hard and managed to get the game working.

=== Project Video ===
*[https://www.youtube.com/watch?v=Ahn2QugTaZU&feature=youtu.be Project Demo]

=== Project Source Code ===
* [https://gitlab.com/akshatbhutiani/bubble-shooter Project Source Code]

== References ==
=== Acknowledgement ===
We would like to sincerely thank Professor Preetpal Kang for his allround guidance, feedback and support. His classroom lectures were significant in imparting knowledge on embedded systems. Further, we would like to thank the ISA team for their advice.

=== References Used ===
* [https://www.adafruit.com/product/512 ADA512 data sheet]
* [https://www.sparkfun.com/products/14718 Sparkfun LED Matrix datasheet]