View source for F21: Flame Over

== Abstract ==
Flame Over is a single-player mode game where the player moves a fire fighter to destroy the fire flames that come shooting at the player using a water gun. The player is granted four lives at the start of the game at each level. The Player’s lives will decrease by one for every three flames that touch the fire fighter. The player transits to the next level when enough flames are destroyed at each level. The speed of the flames approaching the fire fighter varies between levels.

== Objectives & Introduction ==
[[File:Flame over Cover.jpeg|thumb|500x500px|Game Console|right]]

=== Objectives ===
*Write driver module to display game characters and update the display continuously at an optimum refresh rate
*Implement game algorithm for movement of player and flames in real-time, generate water splash bullets.
*Implement player lives count, player health and collision algorithms.
*Write driver module to receive directions from the input device (joystick) via zigbee.
*Fetch Joystick data over ADC and transmit the joystick signals wirelessly via Zigbee  with the help of UART drivers.
*Write driver module to play game sounds via MP3 encoder
*Use FreeRTOS tasks and understand task priority and synchronization.


=== Team Members & Responsibilities ===
*  Naveena Sura
** Game logic and design
** Game implementation
** Built game characters on LED matrix display
** Game Animation Screens
** Bug fixes and optimizations 
** Hardware wiring and assembly 
*  Suganya Nandakumar
** GPIO Driver for LED matrix display
** Built game characters on LED matrix display
** PCB Schematic and Board Design
** Hardware wiring and assembly
** 3D case design and packaging
*  Vaidehi Deshpande
** Joystick Interfacing - ADC driver
** Speaker and MP3 Decoder interfacing
** Zigbee interfacing with UART driver for transmission and reception
** Built game characters on LED matrix display
** Hardware wiring and assembly

== 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/22/2021

|
* Read previous projects, gather information.
* Discussion on RGB LED matrix and Audio Decoder.
* Gathering information regarding Bluetooth module and Joystick interface.
* Finalize part list
* Decide and distribute major roles among team members
* Decide and re-phrase the game rules
| 
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 2
| 
*10/23/2021   
| 
*11/04/2021 
|

*Order necessary parts
*Plan first draft of Wiki schedule 
*Review RGB LED Matrix datasheet.
*Review Audio MP3 decoder datasheet.
*Review the extra hardware needed for RGB LED matrix(Power Adapter)  
*Create Gitlab repository
*Create a shared google drive for the team to share available resources

|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 3
|
*11/05/2021
|
*11/09/2021
|
*Read and familiarize with Bluetooth module(HC-05)
*Start driver implementation for RGB LED matrix
*Test the driver for single row
*Implement functions for all the rows and columns in RGB LED matrix 
*Decide the graphics and character images for the game
*Finalize the Wiki Schedule
 
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>

|-
! scope="row"| 4
|
* 11/10/2021
|
* 11/15/2021
|
*Test the LED driver functioning and should display one of the character from game
*Review the Audio MP3 functioning
*Collect audio samples for different scenarios of the game
*Develop serial MP3 audio encoder driver
*Interface Serial MP3 encoder with SJ2 Board and check for its functioning
*Design driver code for Joystick
*Interface of joystick and SJtwo board and test its functionality
*Synchronize audio MP3 with the joystick movements
*Discuss the techniques to handle obstacles 
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 5
|
*11/16/2021
|
*11/22/2021
|
* Implementation of the game screens on the RGB LED matrix
* Review game collision detection logic
* Synchronize the Audio MP3 with the game graphics
* Start PCB soldering and testing each part after fixing
* RGB LED matrix should handle graphics for different game levels
* Finalize sounds for different scenarios in the game
* Test each module separately and review the code
* Start designing the PCB circuit using a PCB design software.
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 6
|
*11/23/2021 
| 
*11/30/2021
|
*Interface all the sensors, MP3 audio, Bluetooth module, joystick
*Test the whole implementation after integrating all the modules
*Debug and Test all the gaming functionalities for each module
*Add the developed game logic
*Test the game after adding the logic
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 7
| 
* 12/01/2021

| 
* 12/06/2021
|
*Order the final PCB
*Finalize the video game  
*Test the game logic
*Check for the bug fixes
*Start working on Project report
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 8
| 
* 12/07/2021
| 
* 12/13/2021
|
*Update Wiki page
*Work on project report
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
! scope="row"| 9
| 
* 12/14/2021
| 
* 12/16/2021
|
* Individual Assessment
* Final demo
* Update git repo with final code
* Update the Wiki page with game demo link
|
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
* <span style="color:green">Completed</span>
|-
|}

<HR>
<BR/>

== Parts List & Cost ==
{| class="wikitable"
|-
! scope="col"| Item#
! scope="col"| Part Desciption
! scope="col"| Vendor
! scope="col"| Qty
! scope="col"| Cost
|-
! scope="row"| 1
| SJTwo Boards
| From Amazon
| 2
| $100.00
|-
! scope="row"| 2
| 64x64 RGB LED Matrix
| Adafruit
| 1
| $92.00
|-
! scope="row"| 3
| Wiring Components and  Cable
| Amazon
| 1
| $20
|-
! scope="row"| 4
| Digi Xbee module
| From Preet
| 2
| $0
|-
! scope="row"| 5
| HiLetGo Analog 2-axis thumb Joystick 
| Amazon
| 1
| $9
|-
! scope="row"| 6
| MP3 music player (YX5300)
| Amazon
| 1
| $8
|-
! scope="row"| 7
| 5V,4A Power Adapter  
| Amazon
| 1
| $20
|-
|-
|}

== Design & Implementation ==
The design section can go over your hardware and software design.  Organize this section using sub-sections that go over your design and implementation.

=== '''Pin Configuration''' ===
<div><ul>
<li style="display: inline-table;">
{| class="wikitable" style="width: 100%"
|-
! scope="col" style="background:#ADD8E6;"|<span style="color:#FFFFF"> <font size=3> Pin Function </font></span>
! scope="col" style="background:#ADD8E6;"|<span style="color:#FFFFF"> <font size=3> SJ2 Main Board Pin Configuration </font></span>  
! scope="col" style="background:#ADD8E6;"|<span style="color:#FFFFF"> <font size=3> SJ-2 PIN </font></span>
|-
! scope="row"| R1
| PIN for Red terminal of RGB LED for the upper half of LED Matrix
! P1_1
|-
! scope="row"| G1
| PIN for Green terminal of RGB LED for the upper half of LED Matrix
! P1_14
|-
! scope="row"| B1
| PIN for Blue terminal of RGB LED for the upper half of LED Matrix
! P1_4
|-
! scope="row"| R2
| PIN for Red terminal of RGB LED for the lower half of LED Matrix
! P0_6
|-
! scope="row"| G2
| PIN for Green terminal of RGB LED for the lower half of LED Matrix
! P0_7
|-
! scope="row"| B2
| PIN for Blue terminal of RGB LED for the lower half of LED Matrix
! P0_8
|-
! scope="row"| A
| Mux pin for row selection
! P0_26
|-
! scope="row"| B
| Mux pin for row selection
! P1_20
|-
! scope="row"| C
| Mux pin for row selection
! P1_23
|-
! scope="row"| D
| Mux pin for row selection
! P1_28
|-
! scope="row"| E
| Mux pin for row selection
! P1_31
|-
! scope="row"| OE
| Output Enable
! P2_2
|-
! scope="row"| LATCH
| Data Latch
! P2_5
|-
! scope="row"| CLK
| Clock Signal
! P2_4
|-

! scope="row"| 
! scope="col" | MP3 Decoder 
| 
|-
! scope="row"| RX
| UART Receive From MP3 Decoder
! P4_29
|-
! scope="row"| TX
| UART Send Command from SJ-2 Main Board
! P4_28
|-

! scope="row"| 
! scope="col"| XBEE Module Receiver
| 
|-

! scope="row"| RX
| UART Receive From Game Controller
! P2_9
|-
! scope="row"| VCC
| VCC Supply
! VCC 3.3
|-
|}
</li>
<li style="display: inline-table;">
{| class="wikitable" style="width: 100%"
|-
! scope="col" style="background:#ADD8E6;"|<span style="color:#FFFFF"> <font size=3> Pin Function  </font></span>
! scope="col" style="background:#ADD8E6;"|<span style="color:#FFFFF"> <font size=3> SJ2 Joystick Control Board Pin Configuration  </font></span> 
! scope="col" style="background:#ADD8E6;"|<span style="color:#FFFFF"> <font size=3> SJ2 PIN  </font></span>
|-


! scope="row"| 
! scope="col" | XBEE Module Transmitter 
| 
|-

! scope="row"| TX
| UART Transmit to Main Board 
! P0_10
|-
! scope="row"| VCC
| VCC Supply
! VCC 3.3
|-

! scope="row"| 
! scope="col" |Joystick 
| 
|-

! scope="row"| VCC
| VCC
! 3.3V
|-
! scope="row"| GND
| GND
! GND
|-
! scope="row"| Vx
| X-axis ADC Reading for character movement
! P0_25
|-
! scope="row"| Vy
| Y-axis ADC Reading for character movement
! P0_25
|-

|}
</li>
</ul></div>

=== LED Matrix ===
A 64x64 RGB LED Matrix Panel is used as a display. It has 64 rows and 64 columns. It is divided into two 32x64 sections. A LED or pixel (which we use in subsequent sections) can be accessed and controlled individually. A decoder is used to access individual row. One row can be selected at a time using A,B,C,D and E pins. This enables us to select one row in each of the 32X64 sections. Columns are controlled using shift registers, every bit in the shift register controls the corresponding column. On every falling edge of the clock pulse, the values at R1, B1, G1, R2, B2, and G2 pins are stored into the shift register and the register shifts the data by one bit. After this, the data on the shift register is passed onto the individual LED's when both OE and LE pins are set to high.

<center>
<table>
<tr>
<td>
[[File:led_matrix_front.jpg|thumb|400x300px|right| LED Matrix front View]]
</td>
<td>
</td>
<td>
[[File:RGB LED Matrix Panel32x64.jpg|thumb|400x300px|left| LED Matrix rear View]]
</td>
</tr>
</table>
</center>

<center>
<table>
<tr>
<td>
LED matrix pins:
{| class="wikitable"
|-
! align="center"|S.NO
! align="center"|RGB LED pins
! align="center"|SJone GPIO pins
|-
| scope="row" align="center"|1
| scope="row" align="center"|R1
| scope="row" align="center"|P2.5
|-
| scope="row" align="center"|2
| scope="row" align="center"|G1
| scope="row" align="center"|P0.1
|-
| scope="row" align="center"|3
| scope="row" align="center"|B1
| scope="row" align="center"|P0.18
|-
| scope="row" align="center"|4
| scope="row" align="center"|R2
| scope="row" align="center"|P0.15
|-
| scope="row" align="center"|5
| scope="row" align="center"|G2
| scope="row" align="center"|P2.9
|-
| scope="row" align="center"|6
| scope="row" align="center"|B2
| scope="row" align="center"|P2.7
|-
| scope="row" align="center"|7
| scope="row" align="center"|A
| scope="row" align="center"|P2.4
|-
| scope="row" align="center"|8
| scope="row" align="center"|B
| scope="row" align="center"|P0.0
|-
| scope="row" align="center"|9
| scope="row" align="center"|C
| scope="row" align="center"|P0.22
|-
| scope="row" align="center"|10
| scope="row" align="center"|D
| scope="row" align="center"|P0.17
|-
| scope="row" align="center"|11
| scope="row" align="center"|CLK
| scope="row" align="center"|P0.16
|-
| scope="row" align="center"|12
| scope="row" align="center"|OE
| scope="row" align="center"|P2.8
|-
| scope="row" align="center"|13
| scope="row" align="center"|LAT
| scope="row" align="center"|P2.6
|-
| scope="row" align="center"|14
| scope="row" align="center"|VCC
| scope="row" align="center"|3.3V
|-
| scope="row" align="center"|15
| scope="row" align="center"|GND
| scope="row" align="center"|GND
|-
|}
</td>
<td>
</td>
<td>
[[File:LED_BLOCK_DIAG_AW.png|thumb|700x600px|left| LED Matrix Organisation]]
</td>
</tr>
</table>
</center>

=== Hardware Design ===
=== Software Design and Implementation ===
==== Game Start screen: ====
At the start of the game, a welcome screen is continously displayed until the player is ready and presses the start key. Only on start key press, the freertos game logic tasks are scheduled.

==== Game Design and tasks: ====
We used six freertos tasks of different priorities to control the course of the game: 

* Game display Task
** Refreshes the screen ie., it clears and updates the screen every 3 milliseconds. 
** Draws all the game characters ie., fireman, flames and fireman lives periodically every 3 milliseconds.
** Implements logic to check for level ups, game win or lose status.
** Checks if the fireman was able to successfully put the flames off or if the flames hit the fireman and updates the count of fireman lives based on this.

* Fireman Task: 
** Keeps track of the direction control data transmitted wirelessly from the joystick device from the other board and accordingly updates Fireman position.
** Also has a logic to update water splash trigger flag when the joystick key press signal is received.
 
* Water Splash Task
** Reads the water splash trigger flag that has been updated in ‘Fireman Task’ and controls the movement of water splash bullets. 
** Plays a water bullet sound track every time water splash bullets are released.

* Flame1 Task and Flame2 Task
** Generates Flames on two horizontal tracks from the left and move them towards the right end unless striked by a water bullet, in which case, the flames burst and are put off.
** Generates random starting row positions for each of these flames. 
** Controls the speed of movement of these flames based on the game level.
** Decrements the fireman health every time the fireman is hit by a flame.

==== Collision detection: ====
* Bullet to Enemy Collision
**The movement of bullet and enemy spaceship is stopped and both are cleared from the screen. Kill count is incremented for level up and respective flags are set. Burst animation is played at the collision spot.

*Spaceship to Enemy Collision
**The movement of enemy spaceship is stopped and it is cleared from the screen. Respective flags are set and burst animation is played at the collision spot.

== '''Printed Circuit Board'''==
=== Layout & Design ===

We have designed our Printed Circuit Board using 'AUTODESK EAGLE software', version 9.6.2.The lecture on Eagle PCB provided by Professor Preet provided a good insight about using this software and building a PCB. As suggested during the lecture, we followed Sparkfun Eagle tutorials and libraries while working on the PCB. These resources served as a good source of information for us and made our work easy.

For PCB fabrication, we selected the PCB manufacturer 'JLCPCB' because their production lead-time was less compared to other manufacturers. They had an efficient customer service and faster delivery option that helped us to get our PCBs on time.

'''Schematic and Board Design of PCB'''
       '''1.''' We created a common PCB design for both of our SJ2 Boards.  
       '''2.''' The following connectors were used to design a schematic for our design
                  •LED Matrix        - 10-pin series 057 contact pc board low profile headers
                  •SJ2 Board         - 40-pin series 057 contact pc board low profile headers
                  •Joystick          - 5 pin header
                  •MP3 Serial Player - 4 pin header
                  •Xbee              - Adafruit library Xbee Module

[[File:Board_Layout_Flame_Over.png|thumb|500x600px|Eagle Board Layout|center]]
<center>
<table>
<tr>
<td>
[[File:PCB Board Layout Top Layer.png|thumb|500x600px|PCB Layout - Top Layer|left]]
</td>
<td>
</td>
<td>
[[File:PCB Board Layout Bottom Layer.png|thumb|500x600px|PCB Layout - Bottom Layer|left]]
</td>
</tr>
</table>
</center>

== '''MP3 Serial Player:''' ==


MP3 Serial Player module is a simple MP3 player device which is based on a high quality MP3 audio chip. It can support 8kHz - 48kHz sampling frequency MP3 and WAV file formats. Also, this board has a TF card socket so that a SD card can be inserted that stores audio files. SJTwo board can control this module via UART port, such as switch songs, change the volume and play mode, and so on. 

The SD card should be formatted as FAT16 or FAT32 and should have some audio files with .mp3 or .wav formats. If user wants to create separate folders then those should be created as “01”, “02” and the songs should be with the names 001xxx.mp3/ 002xxx.mp3/ 003xxx.mp3 in those created folders.

=== Hardware Interface ===
Universal Asynchronous Receiver Transmitter (UART) is used as an interface to connect SJTwo board and MP3 Serial Player. UART_3 is configured for YX5300 MP3 player. Below is the pinout connections between UART and MP3 Serial Player: 




=== Software Design ===
Show your software design.  For example, if you are designing an MP3 Player, show the tasks that you are using, and what they are doing at a high level.  Do not show the details of the code.  For example, do not show exact code, but you may show psuedocode and fragments of code.  Keep in mind that you are showing DESIGN of your software, not the inner workings of it.  

=== Implementation ===
This section includes implementation, but again, not the details, just the high level.  For example, you can list the steps it takes to communicate over a sensor, or the steps needed to write a page of memory onto SPI Flash.  You can include sub-sections for each of your component implementation.

== Testing & Technical Challenges ==
This section includes information about testing and the technical challenges we faced while developing this project

* Technical Challenges
'''Flickering of data -'''
Finding a good refresh rate was crucial for the display. The screen ended up flickering for few refresh rates. The task design had to be curated and the refresh rate had to be reevaluated to mitigate flickering. 
Also, initially when we started with the project and were interfacing the LED matrix display, we were having issues of random pixels being lit. We referred to online sources and GitHub links of previous projects to see what we were doing wrong. We later changed our initializing sequence and it started working fine and all the issues disappeared.

'''SD card formatting and file structure -'''

Songs are referenced by folder and by song ‘index’, although it seems that the numeric index is sometimes ignored and the songs played in the order they are stored in the SD card. The documentation is unclear on this and seems to imply both situations. So, even if you plan only one playlist, it is better to keep them in a ’01’ folder and save all the songs to the SD card at the same time.

'''Exhausting UART peripherals -'''

We initially planned of interfacing the communication from the display board to the sound board over uart peripheral, as the project went on and since the master board has a bluetooth module to receive data from the joystick which is interfaced over uart too. We exhausted the uart peripherals on the sj two board, as the uart2 and uart4 were not getting iniitialized for some reason. Hence we had to change the interfacing protocol to i2c, where the display was the master and the sound board was the slave. The slave board was already using uart3, we had planned of using tx for communicating with the mp3 module and rx for receiving the commands from the display board. 
Finding game sounds to suit our game took a while, as we were looking for free sounds and many websites were selling it for price.

== Conclusion ==
Working on this project has helped us gain hands-on experience in working with real time systems. We implemented various concepts that we learned in our class. We developed ADC, UART, GPIO drivers on ARM based microcontroller. Working with FreeRTOS tasks we understood the importance of various factors such as semaphores, task priority, task delay. Even though we faced many challenges working hard to solve them was truly rewarding. Apart from technical knowledge we learned other skills such as teamwork, using GIT etc.

=== Project Video ===
[https://youtu.be/dpbmW8NvA4U Project Demonstration Link]

=== Project Source Code ===
*  [https://sourceforge.net/projects/sjsu/files/CmpE_S2016/ Sourceforge Source Code Link]

== References ==
=== '''Acknowledgement''' ===

We would like to thank our Professor Preetpal Kang for designing a great course which really engages the students and is thought provoking. We'd also like to thank our ISA team for being there whenever we were stuck on various stages of this course and timely help with the Project. Finally, the credit goes to our entire team, Flame Over. With full support and cooperation from each other, we were successfully able to complete this project as planned.

=== '''References Used''' ===

*https://bikerglen.com/projects/lighting/led-panel-1up/
*[http://www.socialledge.com/sjsu/index.php?title=Realtime_OS_on_Embedded_Systems FreeRTOS documentations]
*[https://learn.adafruit.com/32x16-32x32-rgb-led-matrix/overview 32x32 LED Matrix by Adafruit]
*[https://github.com/adafruit/Adafruit-GFX-Library Adafruit Github Library]
*[https://github.com/adafruit/Adafruit-GFX-Library Adafruit Github Library]
*[http://socialledge.com/sjsu/index.php/Main_Page WikiPage by Preetpal Kang]
*[https://arduinoplusplus.wordpress.com/2018/07/23/yx5300-serial-mp3-player-catalex-module/ MP3 commands]

=== Appendix ===
You can list the references you used.