> For the complete documentation index, see [llms.txt](https://docs.launchboard.app/cxd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.launchboard.app/cxd/internet-of-things-project/references-for-wiring-and-coding/micro-oled-display.md). # Micro OLED Display The [Micro OLED display](https://www.sparkfun.com/products/13003) included in your Photon kit is a monochrome, blue-on-black screen that is 64 pixels in width and 48 pixels in height. It can be used to display text, graphics, or a combination. ![Micro OLED Display](https://576155698-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDgX-RdB-DPZBPuXzJ1%2F-LDgX75Qrx69yS4tZ2_Z%2F-LDgXH0SnETpyqZO048_%2Fmicro-oled.jpg?generation=1527608060206960\&alt=media) The Micro OLED display requires using 7 jumper wires to connect specific OLED pins to specific pins on the Photon board. The OLED pins are located along the top of the OLED display. Line up the pins with different numbered rows on a breadboard, and push down to insert the OLED display pins. Then use jumper wires to connect these rows to the Photon. If the pins along the top of the display were numbered left to right as 1-8, the jumper wire connections would be: | OLED Pin | Photon Pin | | ----------- | ---------- | | Pin 1 - CS | A2 | | Pin 2 - RST | D6 | | Pin 3 - D/C | D5 | | Pin 4 - SDO | (none) | | Pin 5 - SCK | A3 | | Pin 6 - SDI | A5 | | Pin 7 - 3V3 | 3.3V | | Pin 8 - GND | GND | **NOTE:** Several analog pins on the Photon board are duplicated. For example, there are two pins labeled as A2, two A3 pins, two A4 pins, and two A5 pins. However, the OLED only has to connect to a single A2 pin, not both (same goes for A3 and A5 pins). The only limitation is that you will **not** be able to connect another part (such as LED, etc.) to the other A2, A3, or A5 pins. There are two experiments in the online SparkFun Photon Experiment Guide that show how to connect the Micro OLED display to the two different sets of analog pins. Either way works fine: * [Experiment 10](https://learn.sparkfun.com/tutorials/sparkfun-inventors-kit-for-photon-experiment-guide/experiment-10-pong) shows how to connect the OLED to the analog pins on the lower left of the Photon board * [Experiment 11](https://learn.sparkfun.com/tutorials/sparkfun-inventors-kit-for-photon-experiment-guide/experiment-11-oled-apps---weather--clock) shows how to connect the OLED to the analog pins on the upper right of the Photon board. Here is the connection diagram for Experiment 11 showing one way to connect the Micro OLED (ignore the wiring for the three buttons): ![](https://576155698-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LDgX-RdB-DPZBPuXzJ1%2F-LDgX75Qrx69yS4tZ2_Z%2F-LDgXH0YMjO6bNofcIhY%2Fexperiment-11.jpg?generation=1527608060199780\&alt=media) ## Code for OLED Display ### #Include Library Your Photon app must include a code library with special functions that will allow you to control the OLED display. 1. In Particle Build, click on the bookmark icon to open the Libraries sidebar. 2. Type "oled" into the search field. Select the result called: **SPARKFUNMICROOLED** 3. Click the button to "Include in Project" 4. Select the name of your Photon app, and then click the "Confirm" button 5. Particle Build will automatically insert an `#include` statement at the top of your app code ```java // This #include statement was automatically added by the Particle IDE. #include ``` ### Global Variables The following code should be included in your global variables to define certain pins that the OLED is using and to declare a MicroOLED object variable called "oled" that you will use to run the special functions in the OLED library. ```java // global variables #define PIN_OLED_RST D6 #define PIN_OLED_DC D5 #define PIN_OLED_CS A2 // declare MicroOLED object variable called "oled" MicroOLED oled(MODE_SPI, PIN_OLED_RST, PIN_OLED_DC, PIN_OLED_CS); ``` ### setup( ) function You have to include a statement within the `setup()` function to start the OLED display: ```java oled.begin(); ``` ## DISPLAYING TEXT Code for displaying text could be placed within the `setup()` function (only runs once), within the `loop()` function, or within a custom function. Code for displaying text on the OLED screen consists of at least 5 steps: (1) clear the screen, (2) set the cursor position on the screen, (3) set the font type (font size), (4) print text to the screen, and (5) display the updated screen. If desired, steps 2-4 can be repeated to change the cursor position and/or font type for different text that you want to print on the screen. ### 1. Clear Screen To clear the screen: ```java oled.clear(PAGE); ``` ### 2. Set Cursor Position The cursor (starting point for printing) can be set to any x-position and y-position. The OLED is 64 pixels wide by 48 pixels tall. The upper-left corner of the screen is (0,0). ```java // set cursor to top left oled.setCursor(0, 0); ``` ### 3. Set Font Type (Font Size) There are 4 font types (sizes) available. The font type is set by referring to the font type number (0, 1, 2, or 3): ```java // select smallest font oled.setFontType(0); ``` Here are the differences between the font types: | Font Type | Font Size | Font Description | | --------- | --------------------------------- | ------------------------- | | 0 | 5x7 pixels, 10 columns by 6 rows | 255 different characters | | 1 | 8x16 pixels, 6 columns by 3 rows | any character on keyboard | | 2 | 10x16 pixels, 5 columns by 3 rows | only numbers and period | | 3 | 12x48 pixels, 5 columns by 1 row | only numbers and colon | You can mix font types on the screen by printing something in one font type and then switching to a different font type to print something else. ### 4. Print to Screen Text and variable values (integer, float, or String) can be printed to the screen. Text that is longer than the screen column width will automatically wrap to the next line. ```java // print text oled.println("Hello"); // print variable oled.println(userName); ``` However, once the entire screen is filled with text, the screen will **not** scroll. Instead no more new text will be displayed. The screen will have to be cleared in order to display new text. There are two different print commands: `print()` and `println()` * `print()` will print text to the screen, but the cursor will remain on the **same** line. So the next text printed to the screen starts where the last text ended. * `println()` will print the text to the screen, and then move the cursor to the start of a **new** line. So the next text printed to the screen starts on the new line. The `print()` command is helpful for combining text and variables on the same line: ```java oled.print("Time "); oled.print(hour); oled.print(":"); oled.println(minutes); ``` ### 5. Display Updated Screen Text printed to the screen will **not** actually be shown until you specifically tell the OLED to display the updated screen. ```java oled.display(); ``` ### EXAMPLE APP ```java // This #include statement was automatically added by the Particle IDE. #include // global variables #define PIN_OLED_RST D6 #define PIN_OLED_DC D5 #define PIN_OLED_CS A2 // declare MicroOLED object variable called "oled" MicroOLED oled(MODE_SPI, PIN_OLED_RST, PIN_OLED_DC, PIN_OLED_CS); String myName = "Photon"; void setup(){ oled.begin(); } void loop(){ // call custom function displayMessage(); } // custom function void displayMessage() { oled.clear(PAGE); oled.setFontType(1); oled.setCursor(0,0); oled.println("HELLO"); oled.setFontType(0); oled.print("I'm "); oled.println(myName); oled.display(); } ``` ## DISPLAYING GRAPHICS Code for displaying graphics could be placed within the `setup()` function (only runs once), within the `loop()` function, or within a custom function. **More info coming...** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.launchboard.app/cxd/internet-of-things-project/references-for-wiring-and-coding/micro-oled-display.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.