F20: Hungry Snake

Abstract

The player plays a snake that is constantly moving in a direction and its body will move in a trailing fashion.

The goal of the game is survive as long as possible. You will attain points over time and additional points if you "eat" a fruit or enemy.

As you eat more objects, the snake's body will extend so that it will become more difficult over time.

Objectives & Introduction

Show list of your objectives. This section includes the high level details of your project. You can write about the various sensors or peripherals you used to get your project completed.

Team Members & Responsibilities

• Yang Chen
  • Game Development, Code Repo Management
• Yanshen Luo
  • Hardware Development, Music Module, Mechanical Parts(3D Design & 3D Printing)
• David Tang
  • Game Development
• Nuoya Xie
  • Hardware Development - LED Matrix, Controller, PCB Design, and Music Hookup Code

Schedule

TEAM SCHEDULE
Week#	Date	Task	Status
1	10/10/20	Place an order for LED matrix Initial delegation of tasks for different parts of the project Set up splitwise for splitting expenses	Complete Complete Complete
2	10/17/20	Determine initial project content and scope Determine game stages Set up project Git repository	Complete Complete Complete
3	10/24/20	Determine project software architecture Come up with a more detailed spec of the game Plan out how to distribute tasks for software game components Specify smaller code modules needed and start programming	Complete Complete Complete Complete
4	10/31/20	Start developing prototype of game logic for various games screens Start creating LED matrix driver Start creating controller driver	Complete Complete Complete
5	11/7/20	Display letters in LED matrix Controller joystick movement and button push state are correctly obtained using controller getter task Develop prototype for snake movement logic and border detection/collision	Complete Complete Complete
6	11/14/20	Start design of interfacing board between LPC and other components of the system LED matrix can display numbers and strings Controller can detect shaking motion through accelerometer Ability to print game state on console for debugging purposes Initialize game state with multiple sprites Purchase MP3 decoder module Start game enclosure design	Complete Complete Complete Complete Complete Complete Complete
7	11/21/20	Implementing score function in game Finish interface board design Start developing prototype for displaying a score board logic Game start screen design complete Controller driver complete LED matrix can display snake, enemy, and obstacle sprites game logic is able to call LED display and controller driver code and obtain correct values Finish game enclosure	Complete Complete Canceled Complete Complete Complete Complete Complete
8	11/28/20	Finished designing end game screen with score display Snake can interact with obstacles and die from collision Fine tune existing game logic and playability	Complete Complete Complete
9	12/5/20	MP3 module can output different music pieces Implementing fruit and enemy snake logic Interface board PCB manufactured and assembled	Complete Complete Complete
10	12/12/20	Main game SJ2 board can correctly trigger music SJ2 board for sounds and music Game enclosure finished 3D printing Testing all components working together as expected	Complete Complete Complete
11	12/16/20	Demo Day Finalize Wiki report	Complete In-Progress

Parts List & Cost

Top Level
PART NAME	PART MODEL & SOURCE	QUANTITY	COST PER UNIT (USD)
64x64 RGB LED Matrix*	Adafruit	1	$54.95
5V 5A PSU	Amazon	1	$14.99
SJ2 Board	-	2	FREE (each team member has his/her own)
10 pin IDC flat Ribbon Cable	Amazon	1 roll	$7.99
2x5 FC-10P 2.54mm Dual Rows IDC Sockets Female Connector	Amazon	2	$0.46
Hamburger Mini Speaker	Sparkfun	1	$4.95
VS1053 Codec + MicroSD Breakout	Adafruit	1	$24.95

Interface Board
Item #	PART NAME	PART SOURCE	QUANTITY	COST PER UNIT (USD)
1	2 x 20 (40 Pin) Extra Tall Female 0.1 Inch Pitch Stacking Header	Amazon	1	$1.375
2	2X5 10Pins 2.54mm Pitch Straight Pin Connector IDC Header	Amazon	1	$0.24
3	2X8 16Pins 2.54mm Pitch Straight Pin Connector IDC Header	Amazon	1	$0.28
4	TB006-508-02BE Screw Terminal Block	DIGIKEY	1	$0.77
5	RSTA 3.15 AMMO Fuse	DIGIKEY	1	$0.28
6	TB005-762-02BE Screw Terminal Block	DIGIKEY	1	$0.85
7	2.1mm Barrel Jack Female	DIGIKEY	1	$0.71
8	2.1mm Barrel Jack Female (Breadboard Compatible)	Provided by Yanshen Luo	1	Free
9	3mm LED	Provided by Nuoya Xie	1	Free
10	680Ω resistor	Provided by Nuoya Xie	1	Free

Controller Board
Item #	PART NAME	PART SOURCE	QUANTITY	COST PER UNIT (USD)
1	Analog 2-axis Thumb Joystick w/ select button	AMAZON	1	$1.6
2	12x12x7.3 mm Tactile Push Button	AMAZON	2	$0.64
3	2X5 10Pins 2.54mm Pitch Straight Pin Connector IDC Header	Amazon	1	$0.24
4	LSM303 Triple-Axis Accelerometer	DIGIKEY	1	$14.95
5	standoff with accompany screw and nut	Provided by Nuoya Xie	2	Free
6	2.5mm Female Headers (1x8)	Provided by Yanshen Luo	1	Free
7	3mm LED	Provided by Nuoya Xie	1	Free
8	330Ω resistor	Provided by Nuoya Xie	1	Free

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.

Interface Board Design

Interface Board Finished Product

The purpose of the interface board is to provide stable, permanent connection to the SJ2 board. It includes connections to all the components that are necessary for the game to run. Below are the components of the interface board:

1. 2x20 0.1" pin header to connect to the SJ2 board
   
2. 3.15A fuse to prevent high current passing through the components, in case of an electrical short
   
3. IDC 2x8 shroud connector to the LED matrix signal pins
   
4. Screw terminals for power to the LED matrix(5V), as well as 5V inlet power from power supply
   
5. Optional 2.1mm DC barrel jack for 5V inlet power. Either this jack or the screw terminal can be used to feed power into the interface board
   
6. LED with a current-limiting resistor, indicting when power is provided to the board
   

In order to save manufacturing costs, the interface board is designed so the footprint of the board is as small as possible. The board is a standard two-layer board with silkscreen on both sides. We went with JLC (https://jlcpcb.com/) to manufacture our board.

Interface Board Schematic

Interface Board PCB Layout

Interface Board PCB

Controller Board Design

Controller Board Finished Product

The purpose of the controller board is to obtain user feedback to the game. Similar to a real controller, the controller board contains one joystick that can detect five different directions (up, down, left, right, and center). This is used to control movement of the snake in game. Two buttons, confirm(green) and cancel(red) are included on the board so they can be used to select options on the opening screen. An accelerometer, LSM303, is attached to the controller board through female headers for the ease of removal, in the event which the accelerometer needs to be replaced. The controller board also contains an LED to indicate that the board has been supplied of power. The communication between the controller board and the interface board is through and IDC 10-pin header and ribbon cable. The reason why flat ribbon cable is selected is because the crimper, header, and wire for such cable is cheap and readily available.

Controller Board Schematic

Controller Board PCB Layout

Controller Board PCB

The controller board is designed to be a narrow rectangular so the footprint of the board is as small as possible, yet give enough space for hands to grab confortably. The board is a standard two-layer board with silkscreen on both sides. Similar to the interface board, we went with JLC (https://jlcpcb.com/) to manufacture our board.

Hardware Interface

LED Matrix Display

64 X 64 LED Matrix

LED Matrix Pinout

We chose an 64 x 64 LED Matrix from Adafruit, because we wanted the number of pixels to be as many as possible. The display is controlled by an 2x8 IDC header, which has the following pins:

• R1, G1, B1 - Pins controlling Red, Green, and Blue colors for the upper half of the matrix (32 x 64 LEDs)
• R2, G2, B2 - Pins controlling Red, Green, and Blue colors for the lower half of the matrix (32 x 64 LEDs)
• A, B, C, D, E - Multiplexer pins selecting a single row of the matrix (2 ^ 5 = 32 rows)
• CLK - Clock signal that indicating each shift into the shift register of the LED matrix
• LAT - Once data is shifted into the shift register of the LED matrix, this pin latches the data so they won't be altered
• OE - Output Enable. Used to on the selected row's LEDs on or off

Because we are using 1 bit for each color, a total of 2^3 = 8 colors are available for us to pick from. This also means that all of the pins listed above are simply GPIO pins to control the LED matrix.

At any one point in time, 2 rows (1 on the upper half of the matrix and 1 on the bottom) are selected. These two rows are always off by 32. For example, if row 0 on the top half is selected, then row 0 on the bottom half, which is row 32, is also selected. This means at any one time, two rows are lighted up. However, because of the persistence of vision, human eye can only perceive image at and below 60Hz. This mean if we shift the bits fast enough, we are able to light up "all" of the LEDs on the matrix display.

Controller

Controller consists of:

• One joystick, capable of detecting 5 directions - up, down, left, right, and none (when the controller is not moved)
• Two buttons, one for confirming and one for cancelling of selected options on the start screen
• An accelerometer, LSM303, for detecting movement, such as the shaking of controller by user

Joystick consists of two potentiometers, one for horizontal and one for vertical. When user pushes the stick to a certain direction, both potentiometer contacts are swept across two contacts, creating two voltage dividers. Thus, by reading this voltage using two ADCs, the direction of horizontal and vertical movement can be calculated.

Buttons are connected to GPIO pins that are input direction with a pull-up resistor. When the button is pressed, the input line is connected to ground. Thus, by reading the input pins, if the pin is low, the button is pressed, and vice versa.

LSM303 triple-axis accelerometer from Adafruit

Accelerometer (LSM303) is used in this game to detect controller motion. The sensor can detect acceleration in the x, y, and z coordinate. In our application, we used the z coordinate acceleration to calculate if the controller is been moved up and down. The sensor communicates to the JS2 board using I2C protocol, which means SDA and SCL lines, on top of GND, are connected to the I2C2 peripheral of the microcontroller board.

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.

LED Matrix Display

In order to control the LED matrix and give each pixel its color, the user has to:

1. Select which row (on both top and bottom half of the matrix) using pins A ~ E
2. Disable output on this row of LEDs by setting OE pin
3. Unlatch data by setting the LAT pin
4. For each pixel on the row, clear first, then shift the desired bits into R1, G1, B1, R2, G2, and B2 pins. Set and Reset the CLK pin for each LED.
5. Enable output by resetting the OE pin
6. Have some delay. The longer the delay, the brighter the pixel will be
7. Lastly, disable output by setting the OE pin

All of this code is encapsulated into a function, which is called by a FreeRTOS display task that has highest priority and runs every 10ms. The flow diagram of the display tasks is shown below.

Display Task

Below is the code describing the steps above.

void led_matrix__refreshDisplay(void) {
  for (uint8_t row = 0; row < LED_MATRIX_HALF_LENGTH; row++) {

    led_matrix__select_row(row);
    led_matrix__disable_output();
    led_matrix__unlatch_data();
    led_matrix__clock_in_data(row);
    led_matrix__latch_data();
    led_matrix__enable_output();
    delay__us(100);
    led_matrix__disable_output();
  }
}

Select Row function:

void led_matrix__select_row(uint8_t row) {
  // set all rows to low first
  LPC_GPIO1->PIN &= ~(1 << D.pin | 1 << E.pin);
  LPC_GPIO2->PIN &= ~(1 << A.pin | 1 << B.pin | 1 << C.pin);

  // row number selected using A to E (5 bits)
  LPC_GPIO2->PIN |= (((row >> 0) & 0x1) << A.pin | ((row >> 1) & 0x1) << B.pin | ((row >> 2) & 0x1) << C.pin);
  LPC_GPIO1->PIN |= (((row >> 3) & 0x1) << D.pin | ((row >> 4) & 0x1) << E.pin);
}

Below is the clock in data function:

void led_matrix__clock_in_data(uint8_t row) {
    for (uint8_t col = 0; col < LED_MATRIX_FULL_LENGTH; col++) {
        LPC_GPIO2->PIN &= ~((1 << R1.pin) | (1 << R2.pin) | (1 << G1.pin) | (1 << G2.pin) | (1 << B1.pin) | (1 << B2.pin));

        LPC_GPIO2->PIN |= (display_matrix_top[row][col].R << R1.pin) | (display_matrix_bottom[row][col].R << R2.pin) |
                      (display_matrix_top[row][col].G << G1.pin) | (display_matrix_bottom[row][col].G << G2.pin) |
                      (display_matrix_top[row][col].B << B1.pin) | (display_matrix_bottom[row][col].B << B2.pin);

        lab_gpio__set(CLK.port, CLK.pin, true);
        lab_gpio__set(CLK.port, CLK.pin, false);
  }
}

Controller

All of the controller-related actions are encapsulated in FreeRTOS tasks. A controller setter task obtains values from controller joystick and buttons and store it in a static global struct variable. The variable is then accessed by the game logic task using a driver function. The obtain controller value task run at 100ms and is low priority. A mutex is used between the setter/getter tasks to prevent simultaneous access to the resource.

Controller Getter and Setter Tasks

Accelerometer

Accelerometer is a separate entity of the controller board - its value isn't obtained by the controller task. This is because usually motion detection using the sensor isn't needed at normal gameplay - it is only triggered when player is battling an enemy snake. Because of this, the task for motion detection is resumed and suspended by other tasks and it doesn't run in a loop.

In order to detect if player is shaking the controller, accelerometer data for the Z-axis is obtained by sending I2C commands to the sensor. According to sensor datasheet, which can be obtained here (https://cdn-shop.adafruit.com/datasheets/LSM303DLHC.PDF), X, Y, and Z-axis acceleration raw values can be obtained from registers 0x28 to 0x2D. Using build-in I2C driver, one can grab all of these bytes with one command. The obtained higher bits need to be shifted in order to recreate the 16-bit raw value, as seen below:

  uint8_t bytes_read[6] = {0};
  i2c__read_slave_data(I2C__2, ACCEL_ADDRESS, (1 << 7 | ACCEL_OUT_X_L_A), bytes_read, 6);
  // convert data to proper format
  int16_t accel_raw_data_X = (int16_t)(bytes_read[0] | (bytes_read[1] << 8));
  int16_t accel_raw_data_Y = (int16_t)(bytes_read[2] | (bytes_read[3] << 8));
  int16_t accel_raw_data_Z = (int16_t)(bytes_read[4] | (bytes_read[5] << 8));

In order to convert the raw value into an actual acceleration unit(m/s^2), a conversion equation is needed. Many internet sources are used to come up with the final equation, as shown below. This equation assumes that the sensor needs to be in 4G and normal mode, which can be configured by the user by writing to the CTRL_REG4_A(0x23) and CTRL_REG1_A(0x20) registers.

static float lsm303__calculate_acceleration_from_raw(int16_t raw_value) {
  const float lsb = 0.00782; // for 4G, normal mode
  const uint8_t shift = 6;   // for normal mode
  const float sensor_gravity_standard = 9.80665; //gravity of earth

  return (float)(raw_value >> shift) * lsb * sensor_gravity_standard;
}

After obtaining the z-axis acceleration value, we can then compare it with earth's gravity, which is 9.8 m/s^2. If the gravity differs greatly from this value in both positive or negative directions, then this means the controller is being moved up or down. The faster the movement, the more difference between the two. We can then set up a threshold value, in which if the obtained acceleration is outside of the threshold, then movement is detected.

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.

Game Design

The code infrastructure is comprised of several major components that allows you to create most type of games.

Sprite Creation

This allows you to specify a body comprised of various pixel coordinates. The body may have gaps between different body parts. This is useful for simulating multiple sprites using a single object which can be moved together.

  sprite_t *enemy = calloc(1, sizeof(sprite_t));
  enemy->type = ENEMY;
  enemy->speed = 8;
  enemy->length = 5;
  enemy->max_length = 10;
  enemy->wrap_around = true;

  coordinates_t enemy_body_parts[] = {{38, 20}, {39, 20}, {40, 20}, {41, 20}, {42, 20}};
  int enemy_body_length = sizeof(enemy_body_parts) / sizeof(coordinates_t);
  sprite_create_linked_bodies(enemy, enemy_body_parts, enemy_body_length);
  add_sprite_to_map(map, enemy);

Movement

There are two modes of movement for the player: on-demand and continuous movement. In on-demand movement, the player sprite will be stationary until a direction input is detected. In continuous movement, the player sprite will constantly move in one direction until the player changes it.

  sprite_t *player = calloc(1, sizeof(sprite_t));
  player->type = SNAKE;
  player->continuous_movement = true;
  // Set initial direction
  player->dir = LEFT;

A separate movement setting can be applied to either the player sprite or NPC that indicates whether the body will move in a TRAIL fashion similar to a snake, or UNIT fashion where all sprite body parts move in the same direction.

  player->move_type = TRAIL;

We have the capability to add advanced movement behaviors for NPCs. You can provide a list of behaviors and it will cycle through all the movements you specify in order.

  behavior_gen_t enemy_behavior_gen_info[] = {
      {TRAIL, true, 5, {RIGHT, RANDOM, RIGHT, RANDOM, RIGHT}},
      {TRAIL, true, 5, {UP, RANDOM, UP, RANDOM, UP}},
      {UNIT, true, 10, {RANDOM, RANDOM, RANDOM, RANDOM, NONE, NONE, RANDOM, RANDOM, RANDOM, RANDOM}}};
  int enemy_behavior_length = sizeof(enemy_behavior_gen_info) / sizeof(behavior_gen_t);
  sprite_create_move_behaviors(enemy, enemy_behavior_gen_info, enemy_behavior_length);

Collision Detection

We use a 64x64 sprite_list_t grid for collision detection. We determine what should happen when two sprites collide based on each type. Currently, we only have the following sprite types: SNAKE (player), OBSTACLE, ENEMY, FRUIT (consumable).

  collision_status_t sprite_collision(game_grid_t *gg, int x, int y, sprite_t *old_sprite, sprite_t *new_sprite) {
    ...
    if (old_sprite->type == SNAKE && new_sprite->type == OBSTACLE) {
      if (gg->dead_sound) {
        gg->dead_sound();
      }
      old_sprite->dead = true;
      return OLD_DIES;
    }
    ...
  }

Game Step

This is a high level function that will be called from the outside to make progress in the game state by one tick. Each call to map->game_step() will internally call sprite_step() for each sprite on the map to update each body accordingly.

  bool game_step(game_grid_t *gg) {
    sprite_list_t *walker = gg->sprite_list;

    while (walker) {
      sprite_step(walker->sprite);
      walker = walker->next;
    }
    return gg->gameover;
  }

Testing & Technical Challenges

Describe the challenges of your project. What advise would you give yourself or someone else if your project can be started from scratch again? Make a smooth transition to testing section and described what it took to test your project.

Include sub-sections that list out a problem and solution, such as:

Dereferencing NULL pointer in linked list game implementation

There were times we tried to put fprintf statements in various places in the code to see where it crashes. However, it was very time consuming to do this. Instead, we created a separate Makefile that uses a separate main.c and compile the code against the hosted environment. This allows us to get a core dump and/or use GDB to inspect memory and walk through our code line by line. The game infrastructure doesn't know about any hardware details so this was not difficult to accomplish.

Conclusion

Conclude your project here. You can recap your testing and problems. You should address the "so what" part here to indicate what you ultimately learnt from this project. How has this project increased your knowledge?

Project Video

Upload a video of your project and post the link here.

Project Source Code

• Primary repository for LED matrix and game implementation
• Separate branch for music decoder

References

Acknowledgement

Any acknowledgement that you may wish to provide can be included here.

References Used

List any references used in project.

Appendix

You can list the references you used.