View source for Public:Onboarding Fall 2021 - Project 2 OLED Display

For this project, you’ll program the MCU to display any message you want on the wheel OLED screen. The OLED screen is a steering wheel screen that we used during FSGP/ASC 2021 to display important messages to the driver like battery voltages, acceleration levels, and battery shutdowns.

This project is more involved than project 1 - you’ll need to read parts of the [https://www.newhavendisplay.com/app_notes/US2066.pdf OLED driver (US2066) datasheet] and learn how to use the Mbed OS SPI class to get the project working.

In this project you'll learn:

# How the SPI protocol works, at least to a general degree
# How to read a datasheet to find necessary hardware information
# How to work more closely with C++ structures like objects and arrays

== The SPI Protocol ==
The MCU communicates with the OLED driver via several pins using the SPI protocol - read the [https://wiki.illinisolarcar.com/w/index.php/General:Firmware#Communication_Protocols wiki section on communication protocols] as well as [https://www.circuitbasics.com/basics-of-the-spi-communication-protocol/ this article about SPI] - make sure to have a ''basic'' understanding of what SPI is.

In our SPI implementation, the MCU is the '''master''' device and the OLED driver is the '''slave''' device. These are outdated terms for good reason, but they help in conceptualizing how SPI works. The MCU master connects to the driver slave via 5 pins:

# 1 pin to send data from the master to the slave (aka. ''master-out, slave-in'' (MOSI) or ''serial data out'' (SDO))
# 1 pin to send data from the slave to the master (aka. ''master-in, slave-out'' (MISO) or ''serial data in'' (SDI))
# 1 pin to send the SPI clock signal
# 1 pin to send the SPI reset signal
# 1 pin to send the SPI chip-select signal

== Getting Started ==
Make sure that you’ve [[MCUXpresso|set up MCUXpresso]] on your computer.

Make sure that you’ve checked out the <code>master_fall2021_onboarding_project2</code> branch on your computer ('''and''' the appropriate submodules). This branch has the starter code for this project, in the mbed15x9_skeleton folder.

Then you want to create your own branch “off” of this branch that contains your (or your group’s) work. '''Do not''' push any changes to the <code>master_fall2021_onboarding_project2</code> branch on Github. That branch contains the starter code that everyone's using.

== The Starter Code ==
The starter code is similar to the starter code given for project 1 (read the project 1 page if you need a refresher on the starter code structure). Again, all the files you’ll be working with are in the inc and src folders in the mbed15x9_skeleton folder.

The biggest difference you’ll notice is that there are new US2066.h and US2066.cpp files in the repository. These files implement the US2066 object which contains all the variables/methods to communicate with the wheel screen US2066 driver.

== What You Need To Do ==
While the US2066.h code is mostly written, you’ll finish some parts of it as well as finish code in other files to get the project working.

=== pins.h ===
First, open pins.h. You’ll notice that there are some macros for the SPI pins that the MCU will use to communicate with the driver. '''The pin numbers are incorrect - you’ll need to figure out what the correct pin numbers are.'''

In your PCB folder in your git repo, open the KiCad schematic in <code>PCB\BRAIN\Brain_v4.0</code> as well as the KiCad schematic in <code>PCB\Ancillary\Breakouts\NHD-0420CW-A_Breakout_v1</code>. The first project is the brain board, containing an MCU, that we used for project 1. The second project is a set of connectors which shows you how we’ll connect the brain to the OLED driver.

What you need to know is that pins 2-6 on connector J8 on the brain respectively connect to pins 5-1 on connector J2 on the NHD-0420CW-A breakout. Based on the MCU pin numbers in the brain schematic and the J2 net labels in the NHD-0420CW-A schematic, you’ll need to figure out what the correct pin numbers for the pins.h pin macros are.

=== US2066.h, US2066.cpp, SPI.h ===
Now open US2066.h and US2066.cpp. Also open <code>mbed/libraries/mbed/api/SPI.h</code>. This is the SPI object, a set of functions/variables that allows you to control the SPI communication between the MCU and driver. 

==== SPI Format and Frequency ====
In the US2066 class, there is a SPI object declared for you to use. Notice in the US2066.cpp _send(...) and _read(...) methods, methods to send and receive data from the driver, you are asked to set the SPI object mode and frequency. The frequency is the frequency of the SPI clock which controls the rate at which data is sent/received. The mode is an additional SPI configuration that controls clock polarity and clock phase - scroll to Table 1 and look at the below figures in [https://www.analog.com/en/analog-dialogue/articles/introduction-to-spi-interface.html#:~:text=SPI%20is%20a%20synchronous%2C%20full,popular%204%2Dwire%20SPI%20interface. this article] for more information. You can set the mode/frequency using methods from the SPI object.

You can figure out what the SPI mode and frequency are by looking at the US2066 datasheet. Look at the '''Max''' “serial clock cycle time” parameter on page 51 - that’s the length of the clock cycle period which you’ll use to figure out the SPI frequency. Then look at the tables on page 10 - those tables are the diagram showing how data is sent/received from the driver based on the SPI clock. Use that diagram to figure out what the SPI mode should be. The linked article above will be especially help for figuring out the SPI mode.

==== SPI Start Bytes ====
In US2066.cpp, you’ll have to figure out what the start bytes for sending or receiving data are in the _send(...) and _read(...) methods. Look at the “Serial Interface” section on pages 9 and 10 to figure out what those should be. A write (send) operation has 3 start bytes, while a read (receive) operation has 1 start byte.

==== Display On, Set Contrast ====
You’ll also have to implement the displayOn(...) and setContrast(...) methods that have been declared in US2066.h (look at the function documentations in US2066.h for more info). You’ll need to send (or receive) the appropriate data/commands to do this.

To figure out how to turn the display on, look at the fundamental command set on page 26. '''Note: only turn the display on or off. Keep the cursor and blink bits off.'''

To figure out how to set the display contrast (brightness), look at the OLED command set on page 30. Notice that you’ll have to send 2 commands to get this working.

'''Notice that for each command, the datasheet command sets tell you whether you are sending a command or data and whether you are writing or reading data.'''

==== _write(...) method ====
Finally, you’ll finish the _write(...) method that actually takes an array of 20 characters (and a line number) and writes it to the screen. The OLED screen has 4 lines of 20 character slots each, which is why the character array must be of length 20. You’ll be writing a loop with a very simple command to do this - look at the write data command on the datasheet page 28 for more details.

=== peripherals.h, peripherals.cpp ===
Now open peripherals.h and peripherals.cpp. You’ll have to actually declare and instantiate your US2066 object where it says so. The SPI and DigitalOut object that you need to instantiate the object have already been written in the pins/peripherals files.

=== main.cpp ===
Now open main.cpp. In the main() method where it says to do so, create 4 20-character arrays with whatever message you want. Use the US2066 write() method to write the characters in those arrays to the screen.