DEV-13628

Page 1 of 12   Photon OLED Shield Hookup Guide Introduction Want your Photon projects to display sensor readings, play pong, or draw little doodles? The Photon OLED Shield might be the perfect fit, and we’re going to show you how to use it. If the OLED screen in the picture above looks familiar, it’s probably because we use the same component in our Microview and Micro OLED Breakout products, as well as the OLED Block for the Edison. We love it for it’s combination of small footprint yet surprisingly clear graphics – the screen itself is 0.66" across, with a display area measuring 64 pixels wide by 48 pixels tall. Please Note: All SparkFun shields for the Photon are also compatible with the Core from Particle. The WKP, DAC and VBT pins on the Photon will be labeled A7, A6 and 3V3*, respectively, on the Core, but will not alter the functionality of any of the Shields. Covered in this Tutorial This tutorial will cover the functionality of the OLED shield, how to hook it up in your project, and how to program with it using the SparkFun Micro OLED Library. Required Materials Page 2 of 12 All you need to get started with the Photon OLED Shield is a Photon, a micro-USB cable, and the OLED shield. You’ll also want to sign up for an account on particle.io and register your photon. Instructions on how to do this can be found at docs.particle.io. Photon Kit SparkFun Photon Micro OLED Shield  KIT-13345  DEV- 13628 9 6 Suggested Reading • Serial Peripheral Interface (SPI) – SPI is the preferred method of communication with the display. • I2C – Alternatively, I2C can be used to control the display. It uses less wires, but is quite a bit slower. OLED Shield Overview Pin Descriptions Since the shield does all of the work for you, there’s no need to actually wire these connections - but in case you’re looking at datasheets, or code for the Microview or OLED breakout, this table will give you a clue as to what the shield is doing. As always, you can check the schematic for more info. OLED Shield Pin GND 3V3 (VDD) Photon SPI Pin Function GND Ground I2C Function Ground 3V3 Power Power Notes 0V Should be a regulated 3.3V supply. D1 (SDI/MOSI) D0 (SCK) A5 MOSI SDA Serial data in A3 SCK SPI and I2C clock D2 (SDO) MISO — SCL Can be unused in SPI mode. No function for I2C. D6 Data / Command D/C I2C address selection — Digital pin to signal if incoming byte is a command or screen data. Page 3 of 12 RST D7 Reset Reset Active-low screen reset. CS A2 — SPI chip select (active-low) — Setting the Jumpers With the board flipped over, you’ll notice there are six jumpers. The majority of these jumpers are used to switch between SPI and I2C mode. As the board ships, these jumpers are set to configure the display in SPI mode. Here’s an overview of each jumper, moving from left-to-right, top-to-bottom in the picture above: • VD/VB -- This jumper shorts the digital power supply (VDD) to the battery power supply (VBAT). Because both of these supplies can be powered at 3.3V, an easy one-supply solution is to short them together and provide them a single supply. If you need to power the digital supply at something lower, like 1.8V, you may need to cut this jumper and provide two supplies. • D1/D2 -- This jumper can be used to short D1 to D2. If you want to use SPI, leave this jumper open. If you're using I2C, short the jumper. By default this jumper is open. • D/C -- This jumper can be used to short D/C to either 3.3V (1) or 0V (0). In I2C mode, the D/C pin sets the 7-bit address of the display. In SPI mode this jumper should be left open, as the D/C pin needs to be toggled to determine if an incoming byte is data or command. • BS2 and BS1 -- These pins on the OLED determine which interface you're using to control the OLED. With the two signals, there are four possible combinations: BS2BS1Interface 0 0 SPI 0 1 I2 C 1 0 8-bit Parallel (6800) 1 1 8-bit Parallel (8080) By default, both of these jumpers are set to 0, which puts the display in SPI mode. If you want to change it to I2C mode, clear the BS1 jumper and set it to 1. That brief overview should cover the 99% use case. Consult the schematic and the notes therein if you have any questions about jumpers or pins. Using the OLED Shield When attaching your Photon to the top of the OLED shield, make sure the beveled end of your Photon (next to A0 and D0) matches up with the beveled lines on the top of the OLED shield (the end with the Open Source Hardware Logo). The pin labels on the Photon should match those on the OLED shield as well. You can stack many of our Photon shields together, which is why the OLED screen juts out to the side. So, you can end up with something like this: Page 4 of 12 Using the Particle OLED Library Great, now that we understand the hardware setup, let’s put some code on this thing and see what it can do. Using the Particle library we’ve written, you’ll be able to write text, draw lines and shapes, and generally display anything that’ll fit on the screen. Getting the Particle OLED Library For this page we’ll be using the online Particle environment. If you’re using the Particle Dev environment instead, you can get the library and code examples from the GitHub repository. D O W N L O A D T H E P A RT I CL E O L ED L I B RA R Y Load the Demo Example If you haven’t created a Particle user account and claimed your board, you’ll need to do that now. Starting here is a great idea if you’re having trouble. Once you’re logged into build.particle.io and have a device selected (all this is covered at the link above), you’ll want to click on the create new app button in the sidebar – it’s big and blue, you can’t miss it. Call your app something like ‘OLED_test’. Next – this is the important part – we include the SparkFunMicroOLED library. To do this: • Click on the icon that looks like a bookmark (it’s all the way to the left on the black skinny sidebar, 4th up from the bottom) • In the text box under ‘community libraries’, search for ‘OLED’ and you’ll see ‘SparkFunMicroOLED’ come up (though it might be cut off a little bit, don’t worry). It should look something like this: Page 5 of 12 • Click on the library name, and a bunch of stuff will pop up, including all the library files as well as a few options of what to do with the library. • In this case, we just want to use the library in our app, so click on the ‘include in app’ button. • This will lead you to list of all your apps - click on the name of the app you just created, and you should see a statement like #include "SparkFunMicroOLED/SparkFunMicroOLED.h" at the top of your app. • Last thing is to add the math library to our sketch - on the line below the first #include statement, type in: #include "math.h" Now that we’ve included the library in our app, let’s give it some code - just copy the demo code below and paste it into your app, below the include statements. Page 6 of 12 /*  Micro­OLED­Shield­Example.ino  SparkFun Micro OLED Library Hello World Example  Jim Lindblom @ SparkFun Electronics  Original Creation Date: June 22, 2015  This sketch prints a friendly, recognizable logo on the OLED S hield, then    goes on to demo the Micro OLED library's functionality drawi ng pixels,    lines, shapes, and text.    Hardware Connections:    This sketch was written specifically for the Photon Micro OL ED Shield, which does all the wiring for you. If you have a Mi cro OLED breakout, use the following hardware setup:      MicroOLED ­­­­­­­­­­­­­ Photon        GND ­­­­­­­­­­­­­­­­­­­ GND        VDD ­­­­­­­­­­­­­­­­­­­ 3.3V (VCC)      D1/MOSI ­­­­­­­­­­­­­­­­­ A5 (don't change)      D0/SCK ­­­­­­­­­­­­­­­­­­ A3 (don't change)        D2        D/C ­­­­­­­­­­­­­­­­­­­ D6 (can be any digital pin)        RST ­­­­­­­­­­­­­­­­­­­ D7 (can be any digital pin)        CS  ­­­­­­­­­­­­­­­­­­­ A2 (can be any digital pin)    Development environment specifics:      IDE: Particle Build      Hardware Platform: Particle Photon                         SparkFun Photon Micro OLED Shield    This code is beerware; if you see me (or any other SparkFun    employee) at the local, and you've found our code helpful,    please buy us a round!    Distributed as­is; no warranty is given.  */ ////////////////////////////////// // MicroOLED Object Declaration // ////////////////////////////////// // Declare a MicroOLED object. If no parameters are supplied,  default pins are // used, which will work for the Photon Micro OLED Shield (RST =D7, DC=D6, CS=A2) MicroOLED oled;  void setup() {    oled.begin();    // Initialize the OLED   oled.clear(ALL); // Clear the display's internal memory   oled.display();  // Display what's in the buffer (splashscre en) delay(1000);     // Delay 1000 ms   oled.clear(PAGE); // Clear the buffer. randomSeed(analogRead(A0) + analogRead(A1)); }  void loop() {  pixelExample();  // Run the pixel example function Page 7 of 12 lineExample();   // Then the line example function shapeExample();  // Then the shape example textExamples();  // Finally the text example }  void pixelExample() {  printTitle("Pixels", 1); for (int i=0; i paddle1_X)     {  // Check if ball is within paddle's height if ((ball_Y > paddle1_Y) && (ball_Y < paddle1_Y + paddle H))        {          ball_X­­;  // Move ball over one to the left         ballVelocityX = ­ballVelocityX; // change velocity       }      }  // Check if the ball hit the top or bottom if ((ball_Y = (oled.getLCDHeight () ­ ball_rad ­ 1)))     {  // Change up/down velocity direction       ballVelocityY = ­ballVelocityY;     }  // Move the paddles up and down     paddle0_Y += paddle0Velocity;     paddle1_Y += paddle1Velocity; // Change paddle 0's direction if it hit top/bottom if ((paddle0_Y  oled.getLCDHeight()  ­ 2 ­ paddleH))     {        paddle0Velocity = ­paddle0Velocity;     }  // Change paddle 1's direction if it hit top/bottom if ((paddle1_Y  oled.getLCDHeight()  ­ 2 ­ paddleH))     {        paddle1Velocity = ­paddle1Velocity;     }  // Draw the Pong Field     oled.clear(PAGE);  // Clear the page // Draw an outline of the screen:     oled.rect(0, 0, oled.getLCDWidth() ­ 1, oled.getLCDHeight Page 9 of 12 ());  // Draw the center line     oled.rectFill(oled.getLCDWidth()/2 ­ 1, 0, 2, oled.getLCDH eight()); // Draw the Paddles:     oled.rectFill(paddle0_X, paddle0_Y, paddleW, paddleH);     oled.rectFill(paddle1_X, paddle1_Y, paddleW, paddleH); // Draw the ball:     oled.circle(ball_X, ball_Y, ball_rad); // Actually draw everything on the screen:     oled.display(); delay(25);  // Delay for visibility   }  delay(1000); }  void textExamples() {  printTitle("Text!", 1); // Demonstrate font 0. 5x8 font   oled.clear(PAGE);     // Clear the screen   oled.setFontType(0);  // Set font to type 0   oled.setCursor(0, 0); // Set cursor to top­left // There are 255 possible characters in the font 0 type. // Lets run through all of them and print them out! for (int i=0; i= 10) // If ms is >= 10     {        ms = 0;     // Set ms back to 0       s++;        // and increment s     }  delay(1);   }  }  // Center and print a small title Page 11 of 12 // This function is quick and dirty. Only works for titles one // line long. void printTitle(String title, int font) { int middleX = oled.getLCDWidth() / 2; int middleY = oled.getLCDHeight() / 2; oled.clear(PAGE); oled.setFontType(font); // Try to set the cursor in the middle of the screen oled.setCursor(middleX ­ (oled.getFontWidth() * (title.lengt h()/2)), middleY ­ (oled.getFontWidth() / 2)); // Print the title: oled.print(title); oled.display(); delay(1500); oled.clear(PAGE); } Now, click the ‘flash’ button (the one that looks like a lightning bolt) and wait for the magic to begin! Resources & Going Further Here are a few links that should help with any further questions you may have about the Photon OLED Shield: • Photon OLED Shield Github - for schematics and board design files • SparkFun OLED Particle Libarary – this is where to go for the firmware library and example code • Particle Documentation Pages – go here to set up and configure your Photon (or other Particle devices) • Particle Community Forum – anything that you couldn’t find in the docs should be easily found in the community forum. If you are having trouble, search this forum first, as many of the answers are there already. Going Further Now that you’re comfortable with the Photon OLED Shield and its Particle library, what are you going to make with it? Need some inspiration, check out these related tutorials: OLED Display Hookup Guide Serial Graphic LCD Hookup A simple hookup guide to get you started with the OLED LCD. Learn how to use the Serial Graphic LCD. RGB Panel Hookup Guide Reaction Timer Page 12 of 12 Make bright, colorful displays using the 32x32 and 32x16 RGB LED panels. This hookup guide shows how to hook up these panels and control them with an Arduino. Demonstrate mental chronometry with this simple reaction timer! The OLED Shield pairs very well with any of our other Photon Shields; check out our hookup guides for those shields: Photon Battery Shield Hookup Guide Photon Wearable Shield Hookup Guide The Photon Battery Shield has everything your Photon needs to run off, charge, and monitor a LiPo battery. Read through this hookup guide to get started using it. Learn how to use the Photon Wearable Shield for your next projects! Photon IMU Shield Hookup Guide Learn how to use the SparkFun Photon IMU Shield for your Photon device which houses an on-board LSM9DS1 system-in-a-chip that houses a 3-axis accelerometer, 3-axis gyroscope, and 3-axis magnetometer. https://learn.sparkfun.com/tutorials/photon-oled-shield-hookup-guide?_ga=1.239620163.... 10/22/2015