The servo motor included in your Photon kit can rotate back or forth to any position between 0° and ~180° and hold its position.

The servo motor comes with 4 different plastic mounts called "horns" that can be attached to the motor axis (the white part sticking out of the top of the motor – this is what actually rotates). There is a single-arm horn, a double-arm horn, a four-point horn, and a circular horn. Each horn slips onto the motor axis (the horn and axis have matching "teeth"). Each horn has holes, which can allow you to attach something to the horn using the included screws.

NO CONTINUOUS ROTATION

This servo motor can rotate to a specific angle (up to ~180°) and hold its position. It does NOT rotate continuously, like a motor used in a fan or an engine. If your IoT device requires a motor that can rotate continuously, then you need a gear motor or a continuous rotation servo motor.

How to Connect Servo Motor

The servo motor has a built-in 3-wire connector. You'll plug 3 jumper wires into the connector, and then plug the other end of each wire into the breadboard or directly into a pin on the Photon circuit board.

Requires PWM Pin

The white wire of the servo motor must be connected to an I/O pin capable of pulse-width modulation (PWM), which is a process used to make a digital output signal (which has only two values: HIGH or LOW) act like an analog output signal (which has a range of values).

These Photon I/O pins are capable of PWM output: A4, A5, D0, D1, D2, D3, RX, TX, WKP.

Connect to Photon

To connect a servo motor to your Photon using the breadboard, you will need:

• Servo Motor (with 3-wire connector)

• 3 jumper wires (use different colors to help identify them; it may help to match the motor wires)

Here are the steps to connect the servo motor to your Photon using the breadboard:

1. Plug one end of a jumper wire into the motor's white wire connector. Plug the other end of this jumper wire into a PWM-capable I/O pin on the Photon circuit board.

2. Plug one end of a second jumper wire into the motor's red wire connector. Plug the other end of this jumper wire into either the VIN pin or V-USB pin on the Photon circuit board (or to a positive power rail on the breadboard that is connected to VIN or V-USB). If your Photon is being powered through the barrel jack, connect to the VIN pin. Otherwise, if your Photon is being powered through the Micro-USB port, connect to the V-USB pin.

3. Plug one end of a third jumper wire into the motor's black wire connector. Plug the other end of this jumper wire into a pin hole connected to GND: either plug it into a negative power rail on the breadboard (which is connected to GND via a different jumper wire), or plug it directly into a GND pin on the Photon circuit board.

Here's a wiring diagram showing a possible way to connect a servo motor (ignore the wiring for the push button):

Keep in mind that your connection can look different than this example diagram:

• Your servo motor's white wire could connect to a different I/O pin capable of PWM output. (The example connects to the D0 pin on the Photon circuit board).

• Your servo motor's red wire could connect to either the VIN pin or V-USB pin – or to a positive power rail connected to one of these pins. (The example connects directly to the V-USB pin.)

• Your servo motor's black wire could connect either to a different GND pin or to a negative power rail connected to a GND pin. (There are three available GND pins.)

• Alternatively, you could connect the servo motor's wires into different terminal strip rows on a breadboard, and then use 3 additional jumper wires to connect to the Photon circuit board.

Connect Horn to Motor

Be sure to attach one of the horns to your servo motor. Otherwise, rotating the motor won't provide much use to your device.

Later, once you test out your code to rotate the servo motor, you may need to remove and re-position the horn, so it's lined up where you want it to be as it rotates to specific angles. The best way to do this is to rotate the servo motor to 0° (or another specific angle, such as 90°) and then remove & re-position the horn to be pointed correctly for this particular angle.

How to Code Servo Motor

The basic steps to control a servo motor in your app code are:

1. Declare a global variable to store the I/O pin number for the servo motor.

2. Create a Servo object assigned to a global variable called servo.

3. Use a sequence of servo.attach(), servo.write(), and servo.detach() statements to rotate the motor to a specific angle.

Library

The servo motor requires a code library that defines a class called Servo which has built-in methods (functions) for controlling the motor. However, this library is already included in the Particle firmware on your Photon device, so you do not need an #include statement to add the library to your app.

Global Variables

You should declare a global variable to store the I/O pin number that the servo motor is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the servo motor to a different pin number).

You will also need to create an object using the Servo class included in the Particle firmware, and assign this object to a global variable.

Add this code (modify if necessary) before the setup() function:

int motor = D0;
Servo servo;

The first line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called motor. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D0. If necessary, modify this value to match the actual I/O pin that your servo motor is connected to.

The second line of code creates a new object using the Servo class, and assigns the object to a global variable named servo.

NOTE: The Servo class name starts with an uppercase letter "S", while the servo object variable name starts with a lowercase letter "s".

Function to Rotate Servo

The servo motor can rotate back or forth to any position between 0° and ~180° and hold its position.

Rotating the servo motor to a specific angle requires a sequence of four steps:

1. Turn on the motor using the servo.attach() method.

2. Rotate the motor to a specific angle using the servo.write() method.

3. Allow time for the motor to finish rotating by using the delay() method.

4. Turn off the motor using the servo.detach() method.

You'll add a custom function named rotateServo() that will contain all these steps. The function will accept a parameter representing the desired angle of rotation.

Add this rotateServo() custom function after the loop() function:

void rotateServo(int angle) {
    ​servo.attach(motor);
    servo.write(angle);
    delay(500);
    servo.detach();
}

The rotateServo() function requires a parameter for the specific angle of rotation. The parameter value must be an integer (whole number) and will be stored in a local variable named angle.

Here's what the code inside the rotateServo() function does:

1. The servo.attach() method turns on the motor. This method requires the servo motor I/O pin number. In this case, the global variable named motor stores this value. If you used a different name for the global variable storing your servo motor pin number, then insert that name instead.

2. The servo.write() method rotates the motor. This method requires an integer value from 0-180 representing the angle for the rotation. In this case, the parameter variable named angle stores the value that will be used.

3. A delay() of 500 ms (0.5 seconds) is included to give the motor enough time to physically rotate before turning the motor off again.

4. The servo.detach() method turns off the motor. Otherwise, if the motor isn't turned off, the motor will be "jittery" as it tries to hold its position. After you turn off the motor, you may notice that it "debounces" (rotates backward slightly). This is normal.

Calling Servo Function

The rotateServo() function can be called within the setup() function, loop() function, or another custom function.

When calling the rotateServo() function, you must include the desired angle of rotation (0-180) within the parentheses after the function name.

For example, to make the servo motor rotate to an angle of 90°, insert this code statement to call the rotateServo() function:

rotateServo(90);

Read Servo Angle

If necessary, the servo.read() method can be used to get the current angle of the servo motor. The method will return an integer value (whole number) between 0-180 representing the last angle used in the servo.write() method.

Add this code statement wherever you need to read the current angle of the servo motor:

int angle = servo.read();

This code statement creates a local variable named angle to store the integer value returned by servo.read().

LEDs (light-emitting diodes) are small, bright, long-lasting, energy-efficient lights. LEDs have been commonly used in electronic products for decades. More recently, incandescent light bulbs used in homes and other buildings are being replaced with LED light bulbs due to their energy efficiency.

Your Photon kit has a set of LED lights in different bulb colors: red, yellow, green, and blue.

How to Connect LED

Each LED in your Photon kit has a positive leg and a negative leg. These can be identified visually by length: the negative leg has been made slightly shorter.

You will use a breadboard to help connect the LED to your Photon circuit board. The negative leg will be connected to GND (-) through a resistor. The positive leg will be connected to an I/O pin, which will serve as the voltage source (+).

Bend LED Positive Leg

To make it easier to insert the LED into a breadboard, you can carefully bend the positive leg as shown below, so both legs have the same height. You can still identify them visually: the straight leg is the negative leg, and the bent leg is the positive leg.

Bend Resistor Legs

Your Photon kit contains a set of resistors with a resistance rating of 330 Ohms. In order to insert a resistor into the pin holes of a breadboard, you will need to bend both resistor legs into ~90° angles:

Connect to Breadboard

To connect an LED light to your Photon using the breadboard, you will need:

• LED light with bent positive leg

• Resistor with bent legs

• 2 jumper wires (use different colors to help identify them)

Here are the steps to connect the LED light to your Photon using the breadboard:

1. Insert the positive and negative legs of the LED into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as the bent positive leg of the LED. Plug the other end of this jumper wire into an I/O pin on the Photon circuit board.

3. Insert one end of the resistor into the same terminal strip row as the negative leg of the LED. Insert the other end of the resistor into a pin hole of the negative column of the closest power rail on the breadboard.

4. If the negative power rail isn't already connected to a GND pin on the Photon circuit board, then plug one end of the other jumper wire into another pin hole in the negative power rail, and plug the other end of this jumper wire into a GND pin on the Photon circuit board.

Here's a wiring diagram showing a possible way to connect an LED light:

Keep in mind that your connection can look different than this example diagram:

• Your LED legs could be inserted into different row numbers on the breadboard. (The example connects the positive leg to row 20 and the negative leg to row 21.)

• Your LED legs could be inserted into a different column on the breadboard. (The example connects the LED legs into column I of the terminal strip rows.)

• The positive LED leg could connect to a different I/O pin. (The example connects to the D0 pin.)

• The negative power rail on your breadboard could connect to a different GND pin. (There are three available GND pins.)

How to Code LED

The basic steps to control an LED light in your app code are:

1. Declare a global variable to store the I/O pin number for the LED.

2. Set the pin mode for the LED pin in the setup() function.

3. Use digitalWrite() statements to turn the LED on or off. (Another option is to use analogWrite() statements to control the brightness of the LED.)

Global Variable

You should declare a global variable to store the I/O pin number that the LED is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the LED to a different pin number).

Add this code statement (modify if necessary) before the setup() function:

This line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called LED. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D0. If necessary, modify this value to match the actual I/O pin that your LED is connected to.

MULTIPLE LED LIGHTS

If you have multiple LED lights connected to your Photon, then be sure to give each LED a unique variable name by adding an adjective or number to the variable names. For example:

Set Pin Mode

You need to set the pin mode for the LED to be used as an output.

Add this code statement (modify if necessary) within the setup() function:

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named LED is listed. If necessary, change this to match the variable name for your LED.

2. The mode value, which will always be OUTPUT for an LED light because your app will send "on" and "off" signals (or brightness signals) to the LED light.

MULTIPLE LED LIGHTS

If you have multiple LED lights connected to your Photon, then be sure to set the pin mode for each LED pin variable. For example:

Turn LED On or Off

The digitalWrite() method is used to turn an LED on or off.

Add this code statement (modify if necessary) to your app within the setup() function, loop() function, or a custom function:

The digitalWrite() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named LED is listed. If necessary, modify this to match the variable name for your LED.

2. The signal value, which can be HIGH or LOW. Your Photon uses this value to send an electrical signal through the pin: HIGH is a signal of 3.3 volts which represents "on," while LOW is a signal of 0 volts which represents "off." Modify this value to either turn the LED on or off.

Adjust LED Brightness

Alternatively, you can use the analogWrite() method to adjust the brightness of an LED from minimum ("off") to maximum – or any value in-between.

These Photon I/O pins are capable of PWM output: A4, A5, D0, D1, D2, D3, RX, TX, WKP.

Add this code statement (modify as necessary) to your app within the setup() function, loop() function, or a custom function:

The analogWrite() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named LED is listed. If necessary, modify this to match the variable name for your LED.

2. The signal value, which can be any integer value (whole number) between 0-255. Your Photon uses this value to send a PWM electrical signal through the pin: 0 is minimum brightness (LED will be off) while 255 is maximum brightness. In this example, a value of 128 represents 50% brightness. Modify this value based on the brightness needed.

ANALOG VS. DIGITAL

The analogWrite() and digitalWrite() methods are both capable of setting an LED to either minimum or maximum brightness:

• Setting an LED to minimum brightness ("off") using analogWrite(LED, 0) produces the same result as using digitalWrite(LED, LOW)

• Setting an LED to maximum brightness using analogWrite(LED, 255) produces the same result as using digitalWrite(LED, HIGH)

However, the analogWrite() method is the only way to set an LED to a brightness that's in-between these two extremes:

• analogWrite(LED, 64) would set the LED to 25% brightness

• analogWrite(LED, 128) would set the LED to 50% brightness

• analogWrite(LED, 192) would set the LED to 75% brightness

• etc.

Here are references for how to connect and code each physical output in your SparkFun Photon kit:

The small speaker included in the Photon kit can produce tones or play simple music (note by note). The speaker can produce tones ranging in frequency from 20Hz (very low pitch) to 20KHz (very high pitch), covering the full range of sounds that humans can hear.

How to Connect Speaker

The speaker in your Photon kit has a positive leg and a negative leg. These can be identified by labels on the bottom of the speaker:

Also, there is a positive symbol ( ⊕ ) printed on the side of the speaker to identify which side has the positive leg. This allows you to verify the polarity while the speaker is plugged into a breadboard.

Requires PWM Pin

These Photon I/O pins are capable of PWM output: A4, A5, D0, D1, D2, D3, RX, TX, WKP.

Connect to Breadboard

To connect a speaker to your Photon using the breadboard, you will need:

• Speaker

• 2 jumper wires (use different colors to help identify them)

Here are the steps to connect the speaker to your Photon using the breadboard:

1. Insert the positive and negative legs of the speaker into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as the positive leg of the speaker. Plug the other end of this jumper wire into a PWM-capable I/O pin on the Photon circuit board.

3. Plug one end of the other jumper wire into the same terminal strip row as the negative leg of the speaker. Plug the other end of this jumper wire into a pin hole connected to GND: either plug it into a negative power rail on the breadboard (which is connected to GND via a different jumper wire), or plug it directly into a GND pin on the Photon circuit board.

Here's a wiring diagram showing a possible way to connect a speaker:

Keep in mind that your connection can look different than this example diagram:

• Your speaker legs could be inserted into different row numbers on the breadboard. (The example connects the negative leg to row 3 and the positive leg to row 5.)

• Your speaker legs could be inserted into a different column on the breadboard. (The example connects the LED legs into column F of the terminal strip rows.)

• The positive leg of your speaker could connect to a different I/O pin capable of PWM output. (The example connects to the D2 pin.)

• The negative leg of your speaker could connect (through a jumper wire) either to a different GND pin or to a negative power rail connected to a GND pin. (There are three available GND pins.)

How to Code Speaker

The basic steps to control a speaker in your app code are:

1. Declare a global variable to store the I/O pin number for the speaker.

2. Set the pin mode for the speaker pin in the setup() function.

3. Use tone() statements to produce sounds.

Global Variable

You should declare a global variable to store the I/O pin number that the speaker is connected to. This will make it easier to understand your code (and easier to modify the code if you were to connect the speaker to a different pin number).

Add this code statement (modify if necessary) before the setup() function:

This line of code does 3 things (in order):

1. It declares a data type for the variable's value. In this case, int stands for integer (whole number). Photon pin numbers are always treated as int values (even though they have letters).

2. It declares the variable's name. In this example, the variable will be called speaker. You can change the variable name, but choose a name that will make sense to anyone reading the code.

3. It assigns a value to the variable. In this example, the variable's value will be equal to D2. If necessary, modify this value to match the actual I/O pin that your speaker is connected to.

Set Pin Mode

You need to set the pin mode for the speaker to be used as an output.

Add this code statement (modify if necessary) within the setup() function:

The pinMode() method requires two parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D0, etc.) or a variable that stores a pin number. In this example, a variable named speaker is listed. If necessary, change this to match the variable name for your speaker.

2. The mode value, which will always be OUTPUT for a speaker.

Produce Tone

The tone() method is used to produce a sound of a specific frequency (pitch) for a specific duration of time. The speaker can produce tones ranging in frequency from 20Hz (very low pitch) to 20KHz (very high pitch), which covers the full range of sounds that humans can hear.

Add this code statement (modify as necessary) to your app within the setup() function, loop() function, or a custom function:

The tone() method requires three parameters inside its parentheses (in this order):

1. The I/O pin number, which can be the actual pin number (such as: D2, etc.) or a variable that stores a pin number. In this example, a variable named speaker is listed. If necessary, modify this to match the variable name for your speaker.

2. The frequency for the tone, which can be an integer value (whole number) or a variable that stores an integer. The value can be between 20-20000 hertz. Lower numbers will have a lower pitch, while higher numbers will have a higher pitch. In this example, the frequency will be 2000 hertz. Modify this value to the frequency you want for your sound.

3. The duration for the tone, which can be an integer number (whole number) or a variable that stores an integer. The value represents the number of milliseconds that the tone will be played (1000 ms = 1 second). In this example, the duration will be 250 ms (0.25 seconds).

Continuous Tone

If you want to produce a continuous tone that keeps playing, you can either use a negative value for the duration – or you can leave out the duration parameter entirely:

To turn off a continuous tone, use the noTone() method when you're ready to stop the sound:

The Micro OLED display included in your Photon kit is a monochrome (single-color) screen that is 64 pixels in width and 48 pixels in height. It can be used to display text, simple graphics, or a combination. You can even create simple animations by drawing an object, leaving it on the screen briefly, erasing it, and repeating these steps with the object drawn at a new position on the screen.

Although the Micro OLED display is small, it can be useful for displaying information. Since the display is so small, design your information to be "glanceable" – a person should be able to very quickly and easily read and understand the information.

How to Connect Micro OLED

To connect the Micro OLED display to your Photon using the breadboard, you will need:

• Micro OLED display

• 7 jumper wires (use different colors to help identify them)

The Micro OLED has pins located along the top edge of the display. There are labels for each pin printed on the underside of the Micro OLED circuit board.

If the pins along the top edge were numbered left to right as 1-8, the wiring connections would be:

Here are the steps to connect the Micro OLED to your Photon using the breadboard:

1. Insert the 8 pins of the Micro OLED into different terminal strip rows on the breadboard. (Different terminal strip rows have different row numbers.)

2. Plug one end of a jumper wire into the same terminal strip row as the first OLED pin (CS). Plug the other end of this jumper wire into its corresponding pin on the Photon circuit board.

3. Repeat step 2 with the other jumper wires until each OLED pin is connected to its correct Photon pin. NOTE: The fourth OLED pin (SDO) will not be connected to anything.

Here's a wiring diagram showing a possible way to connect a servo motor (ignore the wiring for the three push buttons):

Keep in mind that your connection can look different than this example diagram:

• Your Micro OLED pins could be inserted into different row numbers on the breadboard. (The example connects the OLED pins to rows 1-8 on the right side of the breadboard.)

• Your Micro OLED pins could be inserted into a different column of the breadboard. (The example connects the OLED pins into column F of the terminal strip rows.)

• Your Micro OLED could connect (through jumper wires) to the other A2, A3, and A5 pins located on the lower left side of the Photon circuit board.

• Your Micro OLED 3V3 pin could connect (through a jumper wire) either directly to the 3.3V pin or to a positive power rail connected to the 3.3V pin.

• Your Micro OLED GND pin could connect (through a jumper wire) either directly to a GND pin or to a negative power rail connected to a GND pin. (There are three available GND pins.)

How to Code Micro OLED

The basic steps to control the Micro OLED display in your app code are:

1. Include the SparkFun Micro OLED library in your app.

2. Define the I/O pin numbers for certain Micro OLED pins.

3. Create a MicroOLED object assigned to a global variable called oled.

4. Use the oled.begin() method to start the display in the setup() function.

5. Use various oled methods to display text or simple graphics on the screen.

Include Library

Your Photon app must include a code library that will allow you to control the Micro OLED display.

1. In Particle Build, click on the Libraries icon to open the Libraries menu panel.

2. Type oled into the search field. Select the result called: SparkFunMicroOLED

3. Click the button to "Include in Project"

4. Select the title of your Photon app, and then click the "Confirm" button

Particle Build will automatically insert this #include statement at the beginning of your app code:

// This #include statement was automatically added by the Particle IDE.
#include <SparkFunMicroOLED.h>

Global Variables

You need to define the I/O pin numbers for certain Micro OLED pins. This is similar to declaring global variables (except defined values are not allowed to change).

You will also need to create an object using the MicroOLED class in the included library, and assign this object to a global variable.

Add this code before the setup() function:

#define PIN_OLED_RST D6
#define PIN_OLED_DC  D5
#define PIN_OLED_CS  A2
MicroOLED oled(MODE_SPI, PIN_OLED_RST, PIN_OLED_DC, PIN_OLED_CS);

The first three lines of code define the I/O pin numbers for three specific OLED pins.

The fourth line of code creates a new object using the MicroOLED class, and assigns the object to a global variable named oled.

Start OLED in Setup

The oled.begin() method is used to start the Micro OLED display.

Add this code statement within the setup() function to start the OLED display:

oled.begin();

The oled.begin() method will initialize the settings (including pin modes) for the Micro OLED and turn it on.

Display Text

Displaying text on the Micro OLED screen requires a sequence of five steps:

1. Clear the screen using the oled.clear() method.

2. Set the font type using the oled.setFontType() method.

3. Set the cursor position using the oled.setCursor() method.

4. Print text to the screen using the oled.print() and/or oled.println() methods.

5. Display the printed text using the oled.display() method.

For example:

oled.clear(PAGE);
oled.setFontType(0);
oled.setCursor(0,0);
oled.println("Hello");
oled.display();

1. CLEAR SCREEN

To clear the screen before adding text or graphics:

oled.clear(PAGE);

2. SET FONT TYPE

The SparkFun Micro OLED library includes 4 available font types (numbered 0-3), which differ in font size and in which characters can be displayed:

By default, the Micro OLED will be set to font type 0 by the oled.begin() method.

You can use the oled.setFontType() method to set the font type by including the font type number within the parentheses:

oled.setFontType(0);

You can use a mix of different font types by setting a new font type before printing a new line of text.

For example:

oled.setFontType(0);
oled.println("Hello");
oled.setFontType(1);
oled.println("World");

3. SET CURSOR POSITION

The cursor position represents the starting position for printing text to the screen. The cursor can be set to any (x,y) position on the screen. The OLED screen is 64 pixels wide by 48 pixels tall:

• The x positions are numbered left to right as 0-63

• The y positions are numbered top to bottom as 0-47

For example, to have your text start at the top-left corner of the screen:

oled.setCursor(0,0);

As you print text to the screen, the OLED display will automatically move the cursor position, so the next text printed to the screen will start at the next available screen position.

However, if desired, you can adjust the text layout by setting a new cursor position before printing a line of text, so the new text will start at a specific position on the screen.

For example:

oled.setCursor(20,10);
oled.println("Hello");
oled.setCursor(20,30);
oled.println("World");

4. PRINT TEXT

The oled.print() and oled.println() methods can be used to print text (or variable values) to the screen. Text that is longer than the screen column width will automatically wrap to the next line.

Print Text Within Quotation Marks

To print text directly, include the text inside the method's parentheses by listing the text within double quotation marks:

oled.println("Hello");

Print Value of Variable

To print the value stored in a variable, include the variable name inside the method's parentheses.:

oled.println(myName);

In this case, myName is a variable name (presumably a person's name). Change this to the name of your variable, which could store a text string or number.

Print Decimal Value to Certain Number of Digits

If a variable stores a decimal number (data type is float or double), you have the option of indicating how many digits after the decimal point to show when printing the variable's value:

oled.println(roomTemp, 1);

In this case, roomTemp is a variable name that stores a decimal value (presumably a temperature sensor measurement). Its value will be displayed to 1 digit after the decimal point. So if the actual variable value were 70.1584275, it would be printed on the screen as: 70.2 (the last digit is automatically rounded up if necessary).

PRINT vs. PRINTLN

There are two different print methods that can display text on the Micro OLED screen:

• oled.print() will print text to the screen, but the cursor will remain on the same line. The next text printed to the screen will start where the last text ended.

• oled.println() will print text to the screen, and then move the cursor to the start of a new line. The next text printed to the screen will start on the new line.

The oled.print() command is useful for combining text and variable values on the same line.

For example, if you had a variable named hour that stored the hour of the current time and another variable named minutes that stored the minutes, you could combine these together on the screen:

oled.print("Time ");
oled.print(hour);
oled.print(":");
oled.println(minutes);

Notice that the last code statement used the oled.println() method to move the cursor to a new line for any text that might be printed after the time.

Print Blank Line

To add a blank line, just use the oled.println() method without anything inside its parentheses:

oled.println();

5. DISPLAY SCREEN

Any text or graphics will NOT be shown until the OLED is instructed to display the screen:

oled.display();

Display Graphics

Displaying simple graphics on the Micro OLED screen requires a sequence of three steps:

1. Clear the screen using the oled.clear() method.

2. Draw graphics (dots, lines, rectangles, circles) on the screen using various methods.

3. Display the graphics using the oled.display() method.

For example:

oled.clear(PAGE);
oled.circleFill(32, 24, 10);
oled.display();

Rather than listing all these code statements within the loop() function, you may want to create a custom function that contains all the code to display your graphics. Then you can call this custom function within the loop() function.

The following drawing methods are available:

• oled.pixel() can be used to draw a dot

• oled.line(), oled.lineH(), and oled.lineV() can be used to draw a line

• oled.rect() and oled.rectFill() can be used to draw a rectangle

• oled.circle() and oled.circleFill() can be used to draw a circle

Each drawing method requires parameters for the (x, y) pixel position of a point (or two points if drawing a line). The OLED screen is 64 pixels wide by 48 pixels tall:

• The x pixel positions are numbered left to right as 0-63

• The y pixel positions are numbered top to bottom as 0-47

DRAW DOT

The oled.pixel() method can be used to draw a dot (pixel) at a specific point:

oled.pixel(x, y);

For example, to draw a dot at the center of the screen:

oled.pixel(32, 24);

DRAW LINE

The oled.line() method can be used to draw a line from one point (x1, y1) to another point (x2, y2):

oled.line(x1, y1, x2, y2);

For example, to draw a line from the top-left corner (0,0) to the bottom-right corner (63, 47):

oled.line(0, 0, 63, 47);

DRAW HORIZONTAL LINE

The oled.lineH() method can be used to draw a horizontal line that starts from a specific point (representing the left end of the line) and has a specified width:

oled.lineH(x, y, width);

For example, to draw a horizontal line that starts at (12, 24) and has a width of 40 pixels:

oled.lineH(12, 24, 40);

DRAW VERTICAL LINE

The oled.lineV() method can be used to draw a vertical line that starts from a specific point (representing the top end of the line) and has a specified height:

oled.lineV(x, y, height);

For example, to draw a vertical line that starts at (32, 9) and has a height of 30 pixels:

oled.lineH(32, 9, 30);

DRAW OUTLINE OF RECTANGLE

The oled.rect() method can be used to draw an outline of a rectangle that starts from a specific point (representing the top-left corner of the rectangle) and has a specified width and height:

oled.rect(x, y, width, height);

For example, to draw an outline of a rectangle with its top-left corner at (12, 14) with a width of 40 pixels and a height of 20 pixels:

oled.rect(12, 14, 40, 20);

DRAW FILLED RECTANGLE

The oled.rectFill() method can be used to draw a solid (filled) rectangle that starts from a specific point (representing the top-left corner of the rectangle) and has a specified width and height:

oled.rectFill(x, y, width, height);

For example, to draw a filled rectangle with its top-left corner at (12, 14) with a width of 40 pixels and a height of 20 pixels:

oled.rectFill(12, 14, 40, 20);

DRAW OUTLINE OF CIRCLE

The oled.circle() method can be used to draw an outline of a circle that has its center at specific point and has a specified radius:

oled.circle(x, y, radius);

For example, to draw an outline of a circle with its center at (32, 24) and a radius of 20 pixels:

oled.circle(32, 24, 20);

DRAW FILLED CIRCLE

The oled.circleFill() method can be used to draw a solid (filled) circle that has its center at specific point and has a specified radius:

oled.circleFill(x, y, radius);

For example, to draw a filled circle with its center at (32, 24) and a radius of 20 pixels:

oled.circleFill(32, 24, 20);

DRAW WITH BLACK (ERASING)

By default, all the drawing methods will draw using "white" pixels (which are actually light blue on your Micro OLED screen). However, you can modify each method to draw using black pixels instead, which represents erasing.

Any of the drawing methods can be modified to draw using black pixels by adding BLACK, NORM as the last two parameters inside the method's parentheses.

For example, to draw a black dot:

oled.pixel(x, y, BLACK, NORM);

For example, to draw a black line:

oled.line(x1, y1, x2, y2, BLACK, NORM);

For example, to draw solid (filled) black circle:

oled.circleFill(x, y, radius, BLACK, NORM);

The black pixels will only be visible if drawn on top of a white shape, so the black pixels are erasing white pixels.

For example, this code draws a white filled circle with its center at (32, 24) and a radius of 20 pixels, and then draws a black filled circle that also has its center at (32, 24) but with a radius of 10 pixels:

oled.circleFill(32, 24, 20);
oled.circleFill(32, 24, 10, BLACK, NORM);

By drawing the black circle after the white circle, the black circle will erase part of the white circle.

You can also create more complex patterns by drawing a series of white and black shapes, such as:

oled.circleFill(32, 24, 20);
oled.circleFill(32, 24, 15, BLACK, NORM);
oled.circleFill(32, 24, 10);
oled.circleFill(32, 24, 5, BLACK, NORM);

This example code draws 4 filled circles that have the same center point but a different radius:

1. First, a white filled circle with a radius of 20 pixels is drawn.

2. Then, a black filled circle with a radius of 15 pixels erases part of the white circle.

3. Then, a new white filled circle with a radius of 10 pixels is drawn that fills part of the black circle.

4. Finally, a new black filled circle with a radius of 5 pixels erases part of the second white circle.

The overall pattern ends up looking like a "target" symbol:

SIMPLE ANIMATIONS

You can also create simple animations by drawing something (with white pixels), leaving it on the screen briefly, erasing it (with black pixels), and then changing its position on the screen. A for loop can be used to repeat the "animation" for a certain number of times.

For example, here is code for a simple animation that makes a circle "bounce" back and forth on the screen. The code inside each for loop draws and displays a white filled circle, leaves the circle on the screen for a brief delay(), and then erases the circle (by drawing and displaying a black filled circle of the same size at the same position).

void bouncingCircle() {
    oled.clear(PAGE);  
    // move circle from left to right
    for (int x = 10; x < 54; x++) {
        oled.circleFill(x, 24, 10);
        oled.display();
        delay(20);
        oled.circleFill(x, 24, 10, BLACK, NORM);
        oled.display();
    }
    // move circle from right to left
    for (int x = 53; x > 9; x--) {
        oled.circleFill(x, 24, 10);
        oled.display();
        delay(20);
        oled.circleFill(x, 24, 10, BLACK, NORM);
        oled.display();
    }
}

The first for loop increases the x-position of the circle's center from 10 to 53, which slowly moves the circle across the screen from left to right. The second for loop decreases the x-position of the circle's center from 53 to 10, which moves the circle from the right back to the left.

Display Text + Graphics

You can also combine text and graphics on the OLED screen at the same time. For example:

oled.clear(PAGE);
oled.setFontType(0);
oled.setCursor(18,0);
oled.println("Hello");
oled.circleFill(32, 24, 10);
oled.setCursor(18,41);
oled.println("World");
oled.display();

The Micro OLED display is only 64 pixels in width by 48 pixels in height. Use this limited screen space effectively by designing your text and graphics to be "glanceable" – a person should be able to very quickly and easily read and understand the information.