Assignment Four: Microgalactic Solution

For this assignment, you will program a ship that can explore a tiny galaxy written to the EEPROM module, similar to the classic Zork.
Selected Components

You will need to use the two buttons, potentiometer and EEPROM module.
Setup
I recommend moving the jumper for the green LED (P1.0) off of both pins (you can just put it on one, as the RGB LED jumpers likely were on the board out of the box). This is because the MSP microcontroller communicates with the EEPROM module over this pin (and some others). If you don't do this, the light will always be on. This is expected, but annoying.
To create the galaxy to be explored, you must first run make galaxy in the starting files directory. This will program the microcontroller and it will write the data to the EEPROM. If you have minicom running, it will send some messages indicating its progress. It will also use the red and green LEDs from this assignment. When it says it is finished and the light is solid green, you may erase or flash another program to the MSP.
Objectives
The loc Struct
typedef struct loc {
    char key;
    char sum;
    char name[32];
    char desc[216];
    char exits[6];
} loc;
Structs are basically just a class. If you have completed CS1100 and CS1200, you would have learned about classes. This class has the following fields (or class members, if you'd rather):
    1. key: this is a key byte that will be used to decrypt the location information.
    2. sum: this is a checksum byte that should be equal to 0xFF when decrypted. If the byte is anything other than 0xFF when decrypted, turn on the red LED (P3.6). If the byte is exactly 0xFF then turn on the green LED (P3.2).
    3. name: this is an array of 32 characters that represent the location's name. It will only ever be 31 characters or less and is already null-terminated in the EEPROM data. You don't need to do anything complicated here, simply read all 32 bytes into this field.
    4. desc: this is an array of 216 characters which is the description of the location. Descriptions will often have clues to find important locations to complete the game. It will only ever be 215 characters or less and is already null-terminated. Again, nothing complicated needs to be done, simply read 216 bytes from the EEPROM into this field.
    5. exits: this is an array of 6 characters, each one being a heading that is a possible "exit" from the current location. As it is not supposed to printed as a string, it is not null-terminated. Read 6 bytes from the EEPROM into this field.
Because of the limited memory of the MSP (remember, it only has 512 bytes of RAM), there is only a single one of these structs declared in global scope:
loc current;
Reading Locations from the EEPROM
The EEPROM module is an electrically-erasable programmable ROM that is 8KiB in size (8,192 bytes). This means that valid locations to read data from are 0x0000 to 0x1FFF. The Galactic Center is written to memory location 0x0000, so when the program begins, the first thing to do is to read 256 bytes from this location into the current struct. Every location in the EEPROM is encrypted, so unless you start reading from the correct spot, the data will be garbled as you are "misaligned" in your heading.
You will need to implement the read_loc() function to accomplish this. The first step is to read the very first byte into the .key field. Every byte read after that (255 of them) will need to be XOR'd with this key byte. If the ship is properly aligned and the decryption done properly, the location will be contained in the current variable.
To read data from the EEPROM, call the bool eepromRead(uint16_t address, uint8_t* value) function. The first argument is the address to read a byte from and the second argument is the memory address of some variable. An example of this can be seen with the initialize_dtc() function call during initialization, but you just need to use the & (address of) operator in front of some variable. When the function returns, the value in the variable will be changed to the byte that was read from the EEPROM module.
Printing Locations
The expected output format is as follows:
@ SOL RING { 00 -> 37 -> 71 }
After the human diaspora, the Sol Ring became the home for many. It was constructed centuries ago in orbit around Rigel. There appears to be a smaller ring nearby, but sensors indicate it is not inhabited.
SCANNED HEADINGS:
  42, 71, 00, 00, 00, 00
    1. @ LOCATION: the first line is an at-symbol and the name of the location. It will already be in all caps, you do not have to capitalize it in your software.
    2. { 00 -> 37 -> 71 }: after the location name is the path taken up to this point. You will have to remember the headings for previously visisted locations and add them to an array to keep track of this.
    3. After the human dispora...: on the following line is the description. minicom does not normally wrap lines, so if you would like it to do so, run it like minicom -w.
    4. SCANNED HEADINGS: this is just a static string.
    5. 42, 71, 00, 00, 00, 00: the final line is the listing of exits displayed in hex. The provided hex array will be useful for this display.
Navigation
To navigate the galaxy, you'll need to use the potentiometer. Everything has been set up for you except for actually displaying the selected heading in the console. To do that, you will need to parse out the upper and lower nibbles of the byte for printing inside the main loop. This is the only thing the main loop needs to be doing, everything else will be handled in an interrupt. It looks like this:
// DISPLAY CURRENT HEADING BYTE
cio_printf(">> %c%c", '0', '0');
cio_printf("\b\b\b\b\b");
__delay_cycles(25000);
This will only output >> 00 currently, but you should replace the '0' arguments. This displays the heading, moves the cursor back five characters using \b and then waits ~25ms.
The onboard buttons either move to the selected heading or backward in the list of remembered headings:
#pragma vector=PORT2_VECTOR
__interrupt void engage(void)
This annoying syntax is how to declare that the engage function is an interrupt. The same thing we explored in assignment three is happening, it's just more opaque. Remember that you need to set up the pins the buttons are connected to, to actually cause an interrupt before these functions will work. You do not call these functions in your code.
Find the Flag
If you've implemented all of this, you can now explore the galaxy! There are some clues to locate a secret flag{} value, similar to a Capture the Flag challenge. If you can obtain the flag, send it to me and, if you're the first, you'll be allowed to write your own location to immortalize yourself in Microgalactic history. Future explorers will possibly decrypt your location and laugh, cry or be confused. Awesome!