In this tutorial, you’ll explore the capabilities of the SparkFun Qwiic Shield for Arduino Nano—a modular shield designed to extend the functionality of the Arduino Nano. This shield enables seamless communication between your microcontroller and various I2c-based peripherals like sensors and some displays. It’s a standard connector type that’s been informally adopted by a few other hardware module manufacturers as well. We’ll cover everything from physical setup and orientation to practical demos using sensors available in the ITP shop.
It’s also worth noting that SparkFun’s Qwiic system is fully compatible with Adafruit’s STEMMA QT ecosystem, which uses the same connector and wiring convention. Beyond SparkFun and Adafruit, other companies such as Pimoroni, Seeed Studio, and Pololu have begun integrating this connector into their I2C sensor and breakout boards as well.
What You’ll Need to Know
Before diving in, you should be comfortable with basic Arduino programming and understand the fundamentals of I2C communication. If you need a refresher, review the I2C Communication Labs for in-depth details.
Things You’ll Need
For this tutorial, gather the following components (see Figures 1–6 for reference images):
Figure 1. Arduino Nano 33 IoT or other Arduino Nano BoardFigure 2. SparkFun Qwiic Shield for Arduino Nano
Although the SparkFun Qwiic Shield for Arduino Nano is pinned out exactly like a standard Arduino Nano, it’s still important to verify that you have the correct orientation when mounting the shield. We often reference the 3.3V pin as a quick visual cue to ensure you align everything properly. The shield includes a configurable logic shifting circuit set by the IOREF jumper, which defaults to 3.3V (ideal for boards like the Arduino Nano 33 BLE). If you’re using a 5V Nano variant (such as the Arduino Nano Every), you’ll need to switch the jumper to 5V so that the logic levels match your board’s operating voltage.
Figure 7. Pin alignment guide for powering the SparkFun Qwiic Shield using the Arduino Nano 33 IoT. Ensure that the GND and 3.3V pins are correctly connected to provide stable power and enable Qwiic-based I2C communication.
The Qwiic shield is designed to be mounted below the Nano with which it’s paired. To mount it below would require reversing the standard pin arrangement on the Nano (they are usually on the side of the board without components) and reversing the sockets on the shield.
Figure 8. Arduino on top of the Qwiic shield
Closer Look at the Adapter
The Qwiic adapter is populated with two 4-pin 1mm JST connectors. These connectors are polarized to prevent incorrect insertion, and the pin order follows the Qwiic standard: GND, 3.3V, SDA, and SCL. When mounting the adapter onto the Nano Qwiic Shield, ensure that the labeled side of the adapter aligns with the corresponding pins on the shield to maintain correct orientation.
Figure 9. Qwiic connector pinout diagram showing the standard I2C wire order: SCL, SDA, 3.3V, and GND. The polarized JST connector ensures correct orientation, enabling plug-and-play communication between Qwiic-compatible devices without soldering. sourceFigure 10. A SparkFun Nano Qwiic Shield with a Qwiic cable connected, showing the standard I2C wire orientation. Figure 11. Connector alignment for Qwiic interface: the 4-pin JST cable is shown in correct orientation for insertion into the Qwiic Shield’s port
Connection Diagram
Figure 12 shows the connections between the Qwiic Nano shield and a few typical components.
Figure 12. Wiring diagram for a basic Qwiic I2C setup (Arduino below the shield is not shown in this diagram)
Note that while the Arduino Nano is not shown here, it is connected directly on top of the shield. Note also the placement of I2C communication pins (SDA and SCL). Ensuring the correct physical orientation prevents damage and guarantees reliable operation.
I2C Communication Overview
The SparkFun Qwiic Shield leverages the I2C protocol—a standard for connecting multiple devices with just two wires (SDA and SCL). This tutorial assumes that you’ve reviewed the ITP I2C Communication Labs or Related videos: Intro to Synchronous Serial, I2C for background on the protocol.
I2C Basics
Two-Wire Protocol: Communication occurs over SDA (data) and SCL (clock) lines.
Device Addressing: Each device on the I2C bus is identified by a unique 7-bit address.
Pull-up Resistors: These ensure proper voltage levels on the bus and are often integrated on breakout boards.
Demo Project: Reading Temperature and Humidity on an OLED Display
In this project, we’ll read data from SHTC3 (Humidity and Temp Sensor) and display it on an SSD1306 OLED screen. All components communicate via I2C and connect using Qwiic cables—no breadboards or soldering are required.
Note: Many I2C sensors from providers like SparkFun (Qwiic) and Adafruit (STEMMA QT) come in two variants:
Qwiic/STEMMA QT-compatible versions, which feature JST connectors for plug-and-play wiring (see Figure 13 below) or
Standard breakout boards, which expose I2C pins (SDA, SCL, VCC, GND) but require jumper wires or soldering (see Figure 13 below)
Figure 13. Adafruit APDS9960 Proximity, Light, RGB, and Gesture Sensor – with STEMMA QT / Qwiic connector source
For this demo, we’re using the Qwiic-compatible versions, enabling quick, tool-free connections. However, you can also use standard versions of the same sensors as long as you connect them properly to the corresponding I2C pins.
Hardware Setup
Mount the Shield
Carefully align the Arduino Nano 33 IoT (or other Nano variant) with the SparkFun Qwiic Shield for Arduino Nano.
Ensure the 3.3V pins line up correctly to avoid damaging your board.
Connect the Sensors
Connect sensors to any available Qwiic port using Qwiic cables.
Daisy-chain sensors as needed for project layout.
Attach the OLED Display
If the OLED display includes a Qwiic connector, directly connect it to a free port or daisy-chain.
If not, use a Qwiic Jumper Adapter Cable to connect the necessary pins.
Power and Ground
The Nano’s USB port powers the setup, with the Qwiic Shield distributing 3.3V and GND.
Figure 15. A compact I2C sensor-to-display demo using the Arduino Nano 33 IoT and SparkFun Qwiic Shield.
Install the External Libraries
In the Arduino IDE’s Library Manager (Sketch > Include Library > Manage Libraries…), install the following libraries and dependencies if needed.
In the demo code below, we begin by importing the necessary libraries and defining display parameters such as screen size and I2C address. In the setup() function, we initialize both the SHTC3 sensor and the OLED display, and configure display settings including text size, font, and color. In the loop(), the code reads humidity and temperature data from the sensor every three seconds and updates the OLED screen to show the latest values.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
// Libraries for sensor and display communication
#include<SPI.h>
#include<Wire.h>
#include<Adafruit_GFX.h>
#include<Adafruit_SSD1306.h>
#include<Adafruit_SHTC3.h>
// Instantiate sensor object
Adafruit_SHTC3 shtc3 =Adafruit_SHTC3();
// OLED display resolution and initialization
#defineSCREEN_WIDTH 128
#defineSCREEN_HEIGHT 64
#defineOLED_RESET -1// because the reset pin on the OLED is not being used
// make instances of the sensor elements from the sensor library:
sensors_event_t humidity, temp;
// Get fresh data from sensor
shtc3.getEvent(&humidity, &temp);
// Clear OLED display and set cursor to start
display.clearDisplay();
display.setCursor(0, 0);
// Display temperature readings
display.println("Temperature: ");
display.print(temp.temperature);
display.println(" °C");
display.println("");
// Display humidity readings
display.println("Humidity: ");
display.print(humidity.relative_humidity);
display.println("% rH");
// Update display with new data
display.display();
// Wait for 3 seconds before refreshing
delay(3000);
}
Final Result
Figure 16. Real-time environmental monitoring demo using an Arduino Nano with SparkFun’s Qwiic Shield. The SHTC3 sensor measures temperature and humidity, displaying live data on the SSD1306 OLED screen
Further Use Cases
For a more advanced setup, we can expand the I2C chain by adding more sensors or devices. In the demo below, there is an APDS-9960 gesture sensor and a BMP388 pressure sensor alongside the SHTC3 temperature and humidity sensor. The user can change the data display on the screen by simple hand movement. You can find examples for these sensors at this link.
Figure 17. Chain of I2C sensors and display connected to an Arduino Nano 33 IoT using SparkFun’s Qwiic system.Figure 18. Live sensor data in action—temperature and humidity readings from an SHTC3 sensor are displayed on an OLED screen, while an APDS-9960 gesture and proximity sensor is also daisy-chained via Qwiic. This setup demonstrates how multiple I2C devices can work together seamlessly over a single bus.
Conclusion
The Sparkfun Qwiic Shield can simplify sensor integration and communication with Arduino Nano variants. It’s not the only way to connect IC components, but if you are, and if you’re using a Nano, it’s a handy tool. Whether you’re building a simple temperature monitor or a more complex interactive installation, understanding the practicalities of shield orientation, I2C communication, and connection strategies is key.
In the Introduction to Asynchronous Serial Communication lab, you learned about various methods for managing the communications between computers via asynchronous serial communication. These included formatting your data as ASCII-encoded strings or raw serial bytes and managing the flow of data using handshaking. In the P5.js WebSerial Input Lab, you sent data from one sensor to a personal computer. In this lab, you’ll send data from multiple sensors to a program in p5.js. using the p5.WebSerial library. You’ll use the data from the sensors to create a pointing-and-selecting device (i.e. a mouse).
Figures 1-5 below are the parts you’ll need for this exercise. Click on any image for a larger view.
Figure 1. Microcontroller. Shown here is an Arduino Nano 33 IoT
Figure 2. Jumper wires. You can also use pre-cut solid-core jumper wires.
Figure 3. A solderless breadboard
Figure 4. A pushbutton
Figure 5. two potentiometers. You can use any two analog sensors in place of these if you prefer.
Connect the Sensors
For this exercise, you’re going to need two analog inputs to your microcontroller, and one digital input. It doesn’t matter what they are, so use something that’s easy for you to set up. The photos and schematic in this lab show potentiometers and a pushbutton. You don’t have to use these, though. Any three sensor inputs will do the job. If you’re looking for options, consider:
Figure 6. A joystick, which consists of two potentiometers and a pushbutton
Figure 7. Rotary encoders, which include a built-in pushbutton
Figure 9. Schematic view of an Arduino attached to two potentiometers and a pushbutton. The potentiometers’ center pins are connected to the Arduino’s A0 and A1 inputs, respectively. Their left pins are connected to the voltage bus, and the right pins are connected to the ground bus, respectively. The pushbutton is connected from the Arduino’s voltage output to pin D2. a 10-kilohm connects the junction of the switch and pin D2 to ground.
Figure 10. Breadboard view of an Arduino Uno attached to two potentiometers and a pushbutton. The potentiometers’ center pins are connected to the Arduino’s A0 and A1 inputs, respectively. Their left pins are connected to the voltage bus, and the right pins are connected to the ground bus, respectively. The pushbutton is connected from the Arduino’s voltage output to pin D2. a 10-kilohm connects the junction of the switch and pin D2 to ground.
Figure 11. Breadboard view of an Arduino Nano attached to two potentiometers and a pushbutton. The potentiometers’ center pins are connected to the Arduino’s A0 and A1 inputs, respectively. Their left pins are connected to the voltage bus, and the right pins are connected to the ground bus, respectively. The pushbutton is connected from the Arduino’s voltage output to pin D2. a 10-kilohm connects the junction of the switch and pin D2 to ground.
You’re going to program the microcontroller to read the pushbutton and two analog sensors just like you did in the Intro to Serial Communications Lab. When you have to send multiple data items, you need a way to separate them. If you’re sending them as ASCII-encoded strings, it’s simple: you can just put non-numeric punctuation bytes between them (like a comma or a space) and a unique termination punctuation at the end (like a newline and/or carriage return).
This program will send the two analog sensor values and then the pushbutton. All three will be ASCII-encoded numeric strings, separated by commas. The whole line of sensor values will be terminated by carriage return (\r, ASCII 13) and newline (\n, ASCII 10).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
constintbuttonPin =2; // digital input
voidsetup() {
// configure the serial connection:
Serial.begin(9600);
// configure the digital input:
pinMode(buttonPin, INPUT);
}
voidloop() {
// read the first analog sensor:
intsensorValue =analogRead(A0);
// print the results:
Serial.print(sensorValue);
Serial.print(",");
// read the second analog sensor:
sensorValue =analogRead(A1);
// print the results:
Serial.print(sensorValue);
Serial.print(",");
// read the button:
sensorValue =digitalRead(buttonPin);
// print the results:
Serial.println(sensorValue);
}
When you run this and output it to the Serial Monitor, you should see something like this:
Turn the potentiometers (or tweak the analog sensors) and push the button. Now you’ve got a data format: three sensors, comma-separated, terminated by carriage return and newline. This means that you already have an algorithm for how you’re going to program p5.js to read the serial input. You’ll see that algorithm in the next section.
Receive the data in P5.js
Now write a P5.js sketch that reads the data as formatted by the Arduino program above. The setup will be the same as it was in the Serial Input to p5.js using WebSerial lab. The checklist from that lab lays out all the important parts you need.
The sketch you’re going to write will:
Read the incoming serial data into a string until a carriage return and newline appear
split the string into substrings on the commas
convert the substrings into numbers
assign the numbers to variables to change your programNow that you’ve got a plan, put it into action.
Make a P5.js sketch. If you’re using the p5.js web editor, make a new sketch. Click the Sketch Files tab, and then choose the index.html file. Edit the head of the document as you did for the other p5.webserial labs. It should look like this:
The setup of your sketch will initialize the P5.webserial library and define your callback functions for serial events as you did in other sketches. It should look like this:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
// variable to hold an instance of the p5.webserial library:
constserial =new p5.WebSerial();
// HTML button object:
let portButton;
let inData; // for incoming serial data
let outData; // for outgoing data
function setup() {
createCanvas(400, 300); // make the canvas
// check to see if serial is available:
if(!navigator.serial) {
alert("WebSerial is not supported in this browser. Try Chrome or MS Edge.");
}
// if serial is available, add connect/disconnect listeners:
Change the serialEvent() function to read the incoming serial data as a string until it encounters a carriage return and newline (“\r\n”). Then check to see that the resulting string has a length greater than 0 bytes. If it does, use the split() function to split it in to an array of strings. If the resulting array is at least three elements long, you have your three sensor readings. The first reading is the first analog sensor, and can be mapped to the horizontal movement using the locH variable. The second is the second analog sensor and can be mapped to the locV variable. The third is the button. When it’s 0, set the circleColor variable equal to 255 and when it’s 1, set the variable to 0. Here’s how:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
functionserialEvent() {
// read a string from the serial port
// until you get carriage return and newline:
varinString = serial.readStringUntil("\r\n");
//check to see that there's actually a string there:
if(inString) {
// split the string on the commas:
varsensors = split(inString, ",");
if(sensors.length > 2) {
// if there are three elements
// element 0 is the locH:
locH = map(sensors[0], 0, 1023, 0, width);
// element 1 is the locV:
locV = map(sensors[1], 0, 1023, 0, height);
// element 2 is the button:
circleColor = 255 - sensors[2] * 255;
}
}
}
Note the mappings of sensors[0] and sensors[1]. If you’re not using potentiometers as the first two inputs on your Arduino, then you should use the input mappings for your sensors instead of 0 and 1023. If your analog values are greater than the width of the sketch or the height, the circle will be offscreen, which is why you have to map your sensor range to the screen size.
Program the draw() function to draw a circle that’s dependent on three global variables, locH, locV, and circleColor. Add these three globals to the top of the program:
1
2
3
// variables for the circle to be drawn:
letlocH, locV;
letcircleColor = 255;
Finally, here is the draw function:
1
2
3
4
5
functiondraw() {
background(0); // black background
fill(circleColor); // fill depends on the button
ellipse(locH, locV, 50, 50); // draw the circle
}
If you run this, you should see the circle moving onscreen whenever you change your sensors. When you press the pushbutton, the circle will disappear. Okay, it’s not exactly a mouse, but you are controlling an animation from a device that you built.
Flow Control: Call and Response (Handshaking)
You’ve seen now that by coming up with a serial format (called a protocol), you can write the algorithm for receiving it even before you see any data. You can send multiple pieces of data this way, as long as you format it consistently.
Sometimes you can run into a problem when the sender sends faster than the receiver can read. When this happens, the receiver program slows down as the serial buffer fills up. You can manage this by implementing some form of flow control. The simplest way do to this is using a call-and-response method, where the sending program only sends when it’s told to do so, and the receiving program has to request new data every time it finishes reading what it’s got.
You can add handshaking to the code above fairly simply. Modify the Arduino code as follows. First, add a a new block of code in the setup() This block sends out a message until it gets a byte of data from the remote computer:
1
2
3
4
5
6
7
voidsetup() {
Serial.begin(9600);
while(Serial.available() <=0) {
Serial.println("hello"); // send a starting message
delay(300); // wait 1/3 second
}
}
Now, modify the loop() by adding an if() statement to look for incoming serial data and read it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
voidloop() {
if(Serial.available() > 0) {
// read the incoming byte:
intinByte =Serial.read();
// read the sensor:
intsensorValue =analogRead(A0);
// print the results:
Serial.print(sensorValue);
Serial.print(",");
// read the sensor:
sensorValue =analogRead(A1);
// print the results:
Serial.print(sensorValue);
Serial.print(",");
// read the sensor:
sensorValue =digitalRead(buttonPin);
// print the results:
Serial.println(sensorValue);
}
}
The rest of the sketch remains the same. When you run this and open the serial monitor, you’ll see:
hello
hello
hello
hello
Type any character in the output box and click Send. You’ll get a string of sensor values at the end of your hellos:
510,497,0
Type another character and click Send. It doesn’t matter what character you send, but the loop will always wait for an incoming byte before sending a new set of sensor values. When you write a program to receive this format, it just has to behave the same way you did:
Open the serial port
Wait for a hello
Send a byte to request data
Begin loop:
Wait for one set of data
Send a byte to request new data
end loop
Next, modify the P5.js sketch. Most of the changes are in the serialEvent() function. The initial “hello” messages will trigger this function, so when you get a “hello” or any other string, you need to send a byte back so that the Arduino has a byte available to read. Here’s the new serialEvent():
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
functionserialEvent() {
// read a string from the serial port
// until you get carriage return and newline:
varinString = serial.readStringUntil("\r\n");
//check to see that there's actually a string there:
if(inString) {
if(inString !== "hello") {
// if you get hello, ignore it
// split the string on the commas:
varsensors = split(inString, ",");
if(sensors.length > 2) {
// if there are three elements
// element 0 is the locH:
locH = map(sensors[0], 0, 1023, 0, width);
// element 1 is the locV:
locV = map(sensors[1], 0, 1023, 0, height);
// element 2 is the button:
circleColor = 255 - sensors[2] * 255;
// send a byte back to prompt for more data:
serial.print('x');
}
}
}
}
You also need to add a line to the initiateSerial() function (which is inside the openPort() function) like so:
1
2
3
4
5
functioninitiateSerial() {
console.log("port open");
// send a byte to start the microcontroller sending:
serial.print("x");
}
The reason for this is that if your Arduino is still in the setup() waiting for a byte to arrive, then it needs p5.js to send something when the port is opened. If the Arduino has already broken out of the loop (let’s say you opened the Serial monitor to check), then it is waiting for a byte from p5.js to send the next block of code. Whether it’s in the initiateSerial() function or at the end of the serialEvent() function, by sending a byte when you know the port has just been opened in p5.js, you force the Arduino to send you new data.
That’s it. Your sketch should still run just as it did before, though the serial communication is managed better now, because Arduino’s only sending when P5.js is ready to receive.
You can see the sketch running on GitHub at this link. You can see the source files for copying into the p5.js editor at this link.
Advantages of Raw Binary vs. ASCII
All the examples shown here sent the sensor values as ASCII-encoded strings. As mentioned above, that means you sent three bytes to send a three-digit value. If that same value was less than 255, you could send it in one raw binary byte. So ASCII is definitely less efficient. However, it’s more readable for debugging purposes, and if the receiving program is well-suited to convert strings to numbers, then ASCII is a good way to go. If the receiver’s not so good at converting strings to numbers (for example, it’s more challenging to read a multiple byte string in Arduino than in Processing) then you may want to send your data as binary values.
Advantages of Punctuation or Call-and-Response
The punctuation method for sending multiple serial values may seem simpler, but it has its limitations. You can’t easily use it to send binary values, because you need to have a byte with a unique value for the punctuation. In the example above, you’re using the value 10 (ASCII newline) as punctuation, so if you were sending your sensor values as raw bytes, you’d be in trouble when the sensor’s value is 10. The receiver would interpret the 10 as punctuation, not as a sensor value. In contrast, call-and-response can be used whether you’re sending data as raw binary values or as ASCII-encoded values.
Sometimes the receiver reads serial data slower than the sender sends it. For example, if you have a program that does a lot of graphic work, it may only read serial data every few milliseconds. The serial buffer will get full in that case, you’ll notice a lag in response time. This is when it’s good to switch to a call-and-response method.
Build an Application of Your Own
You just duplicated the basic functionality of a mouse; that is, a device with two analog sensors that affect X and Y, and a digital sensor (mouse button). What applications can you think of that could use a better physical interface for a mouse? A video editor that scrubs forward and back when you tilt a wand? An action game that reacts to how hard you hit a punching bag? An instructional presentation that speeds up if you shift in your chair too much? A music program driven by a custom musical instrument that you design?
Create a prototype in Arduino and P5.js, Node.js, Processing, or whatever programming environment you choose. Come up with a physical interface that makes it clear what actions map to what movements and actions. Figure out which actions can and should be possible at the same time. Present a working software and hardware model of your idea.
In this lab you’ll learn how to send data from p5.js to a microcontroller using asynchronous serial communication.
Overview
When you use the p5.webserial library for P5.js, it uses the W3C’s WebSerial API to allow your browser to communicate with serial ports on your computer. This lab shows you how to use P5 to control a microcontroller using asynchronous serial communication. WebSerial is currently only available in the Chrome and Chromium browsers and the Microsoft Edge browser, so make sure you’re using one of those to do this lab.
Figure 2. LEDs. Shown here are four LEDs. The one on the right is an RGB LED. You can tell this because it has four legs, while the others have only two legs.
Figure 3. Resistors. Shown here are 220-ohm resistors. You can tell this because they have two red and one brown band, followed by a gold band.
Figure 4. An 8 ohm speaker (optional).This is a good alternate to the LED if you prefer audible output.
Prepare the breadboard
Connect power and ground on the breadboard to power and ground from the microcontroller. On the Arduino Uno, use the 5V and any of the ground connections. On the Nano, use 3.3V and the ground connections:
Figure 5. An Arduino Uno on the left connected to a solderless breadboard, right.
Figure 6. Breadboard view of an Arduino Nano mounted on a breadboard.
The +3.3 volts and ground pins of the Arduino Nano are connected by red and black wires(Figure 6), respectively, to the left side rows of the breadboard. +3.3 volts is connected to the left outer side row (the voltage bus) and ground is connected to the left inner side row (the ground bus). The side rows on the left are connected to the side rows on the right using red and black wires, respectively, creating a voltage bus and a ground bus on both sides of the board.Figure 5. Breadboard view of an Arduino Nano connected to a breadboard. The +3.3 volts and ground pins of the Arduino are connected by red and black wires, respectively, to the left side rows of the breadboard. +3.3 volts is connected to the left outer side row (the voltage bus) and ground is connected to the left inner side row (the ground bus). The side rows on the left are connected to the side rows on the right using red and black wires, respectively, creating a voltage bus and a ground bus on both sides of the board.
Connect the LED and resistor to digital I/O pin 11 of the module(Figure 7-8). Alternately, you can replace the 220-ohm LED with a speaker (Figure 9-10). You’ll find code below that uses tones instead of LEDs where appropriate. For more on how to do that, see the Tone Output lab:
Figure 7. Schematic view of an Arduino connected to an LED.
Figure 8. Breadboard view of an Arduino connected to an LED.
Figure 9. Breadboard view of an LED connected to digital pin 5 of an Arduino Nano.
Figure 9 shows a breadboard view of an LED connected to digital pin 5 of an Arduino Nano. The Nano straddles the center of the breadboard in the first fifteen rows. The Nano’s voltage pin (physical pin 2) connects to the board’s voltage bus, and the Nano’s ground pin (physical pin 14) connects to the board’s ground bus. The LED is in the right center of the board, with its anode in one row and the cathode in the next. A 220-ohm resistor connects the LED’s anode to a wire connecting to digital pin 5. The LED’s cathode is connected to the ground bus.
Figure 10. Breadboard view of an Arduino Nano connected to a speaker to digital pin 5.
Figure 10 shows a breadboard view of an Arduino Nano connected to a speaker. The Nano’s ground (physical pin 14) is connected to the ground bus of the breadboard as usual. The red positive wire of the speaker is connected to digital pin 5 of the Arduino. The black ground wire of the speaker is connected to one leg of a 100 ohm resistor. The other leg of the resistor connects to ground.
Program the Microcontroller
Program your Arduino to read the analog input as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
voidsetup() {
Serial.begin(9600); // initialize serial communications
pinMode(5, OUTPUT);
}
voidloop() {
if(Serial.available() > 0) { // if there's serial data available
intinByte =Serial.read(); // read it
Serial.write(inByte); // send it back out as raw binary data
analogWrite(5, inByte); // use it to set the LED brightness
// if you're using a speaker instead of an LED, uncomment line below and comment out the previous line:
// tone(5, inByte*10); // play tone on pin 5
}
}
Only one port at a time can access a serial port.
As you work on this any microcontroller-to-computer application, you will be switching back and forth between the app that programs the microcontroller (in this case, the Arduino IDE) and the app that the microcontroller is communicating with (in this case, p5.js in the browser). You have to keep in mind that only one of these at a time can access a serial port.
That means that when you want to reprogram your Arduino from the Arduino IDE, you should to stop your sketch in the browser window to do so. Then, restart the browser sketch when you’re done reprogramming the Arduino. You don’t need to quit the Arduino IDE each time, because it knows to release the serial port when it’s not programming. However, you do need to close the Serial Monitor in the Arduino IDE when you are using WebSerial in the browser.
The P5.js WebSerial Library
To communicate with your microcontroller serially, you’re going to use the P5.js WebSerial library. If you’re using the p5.js web editor, make a new sketch. Click the Sketch Files tab, and then choose the index.html file. In the head of the document, look for this line:
The sketch you’re going to write will control the microcontroller’s LED from P5.js. Dragging the mouse up and down the canvas will dim or brighten the LED, and typing 0 through 9 will set the LED’s brightness in increments from off (0) through almost full brightness (9). There’s an alternate sketch that will make changing tones if you prefer that instead of a changing LED. The sketch will also receive serial input from the microcontroller just as in the WebSerial Input to P5.js lab, so that you can see that the microcontroller is getting the same values you’re sending.
The setup of your sketch will initialize the P5.webserial library and define your callback functions for serial events. Program the global variables and setup() function as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// variable to hold an instance of the p5.webserial library:
const serial = newp5.WebSerial();
// HTML button object:
letportButton;
letinData; // for incoming serial data
letoutByte = 0; // for outgoing data
functionsetup() {
createCanvas(400, 300); // make the canvas
// check to see if serial is available:
if(!navigator.serial) {
alert("WebSerial is not supported in this browser. Try Chrome or MS Edge.");
}
// if serial is available, add connect/disconnect listeners:
For now you’re leaving the draw() function empty. You’ll fill it in later. You’ll be adding some functions to read mouse dragging and key pressing as well.
Program the draw() function to display the value of any incoming serial bytes. Here it is:
31
32
33
34
35
36
37
functiondraw() {
// black background, white text:
background(0);
fill(255);
// display the incoming serial data as a string:
text("incoming value: "+ inData, 30, 30);
}
To read the mouse and keyboard, you’ll need to write functions to respond to the ‘mouseDragged’ and ‘keyPressed’ events. ‘MouseDragged’ will happen whenever you click and drag the mouse on the canvas. When that happens, read the mouseY, and map its position on the canvas to a value from 0 to 255. Convert the result to a number using the int() function. Then send it out the serial port using the serial.write() function:
39
40
41
42
43
44
functionmouseDragged() {
// map the mouseY to a range from 0 to 255:
outByte = byte(map(mouseY, 0, height, 0, 255));
// send it out the serial port:
serial.write(outByte);
}
The serial.write() function is versatile. If you give it a variable or literal that’s a numeric data type, it will send it as its raw binary value. In the code above, note how you’re converting the output of the map() function to a number using the int() function. If you give it a string, however, it will send out that ASCII string. So be aware of the difference, and make sure you know whether your serial receiving device wants raw binary or ASCII-encoded data.
Program the keyPressed() function similarly to the mouseDragged() function. You want it to read the key strokes, convert them to raw bytes, and send them out the serial port. But you only want to send them if they key hit was 0 through 9. The P5.js variable key returns a numeric value, so you can do math on it and convert it like so:
46
47
48
49
50
51
functionkeyPressed() {
if(key >= 0 && key <= 9) { // if the user presses 0 through 9
outByte = (key * 25); // map the key to a range from 0 to 225
serial.write(outByte); // send it out the serial port
}
}
That’s all you want your sketch to do, so try running it now. You should see that the initial incoming serial value is undefined, but when you drag the mouse up and down, or type 0 through 9, it will update when the Arduino program returns what it received. The LED will also change with these actions.
You can see this sketch running on gitHub at this link. You can get the full text of it at this link.
Sending ASCII-Encoded Serial Data
When you send data from p5.js using p5.webserial, the serial.write() function works like it does in Arduino: it sends numbers as binary data. In the programs above, you’re sending binary data from p5.js and reading it as binary in Arduino.
If you want to send ASCII-encoded serial data from P5.js instead, all you have to do is to serial.print() or serial.println() your string. On the Arduino side, you can read single characters one byte at a time simply as well. However, if you want to convert multi-byte number strings to numeric values, you’ll need a new function to read ASCII encoded numeric strings called parseInt().
Program the Microcontroller Again
To start off with, load a sketch from the Arduino examples called PhysicalPixel. You can find it in the File Menu -> Examples -> Communication -> PhysicalPixel. Here’s what it looks like. Change the LED pin number to pin 5 as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
constintledPin =5; // the pin that the LED is attached to
intincomingByte; // a variable to read incoming serial data into
voidsetup() {
Serial.begin(9600); // initialize serial communication
pinMode(ledPin, OUTPUT); // initialize the LED pin as an output
}
voidloop() {
if(Serial.available() > 0) { // see if there's incoming serial data
incomingByte =Serial.read(); // read it
if(incomingByte =='H') { // if it's a capital H (ASCII 72),
digitalWrite(ledPin, HIGH); // turn on the LED
// if you're using a speaker instead of an LED, uncomment line below and comment out the previous line:
// tone(5, 440); // play middle A on pin 5
}
if(incomingByte =='L') { // if it's an L (ASCII 76)
digitalWrite(ledPin, LOW); // turn off the LED
// if you're using a speaker instead of an LED, uncomment line below and comment out the previous line:
// noTone(5);
}
}
}
When you run this, open the serial monitor and type H or L, and the LED will go on or off. Try typing h or l instead. The LED won’t change, because H and h have different ASCII values, as do L and l. But you can see from this that you don’t need to memorize the ASCII chart to check for character values in your code. Put the character you want to read in single quotes, and the Arduino compiler will automatically convert the character to its ASCII value for you. It only works for single characters, though.
Program P5.js To Control the LED
To get P5.js to control this Arduino program serially, you only need to add to the keyPressed() function to read H or L in addition to 0 through 9. Here’s your new mousePressed() function:
1
2
3
4
5
6
7
8
9
10
11
functionkeyPressed() {
if(key >= 0 && key <= 9) {
// if the user presses 0 through 9
outByte = byte(key * 25); // map the key to a range from 0 to 225
serial.write(outByte); // send it out the serial port
}
if(key === "H"|| key === "L") {
// if the user presses H or L
serial.write(key); // send it out the serial port
}
}
Because the key is already a single character, P5.js sends it out as is, and Arduino reads it as a single byte, looking for the ASCII value of H or L. Notice how the values returned to P5.js are 72 and 76, the ASCII values for H and L. For single characters like this, exchanging data is simple.
If you tried to change the LED with the mouse, you didn’t see anything happen unless your output value was 72 or 76. Why is that?
To see the sketch running on GitHub at this link. You can see the source files for copying into the p5.js editor at this link.
Processing ASCII-Encoded Strings With Arduino
It is also possible to read and interpret ASCII-encoded strings in Arduino. The String.parseInt() function reads an incoming string until it finds a non-numeric character, then converts the numeric string that it read into a long integer. This is a blocking function, meaning that String.parseInt() stops the program and does nothing until it sees a non-numeric character, or until a timeout passes. The timeout is normally one second (or 1000 milliseconds), but you can set it to a lower number of milliseconds using Serial.setTimeout(). Here’s a variation on the original Arduino sketch from above, using Serial.parseInt() this time:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
voidsetup() {
Serial.begin(9600); // initialize serial communications
Serial.setTimeout(10); // set the timeout for parseInt
pinMode(5, OUTPUT);
}
voidloop() {
if(Serial.available() > 0) { // if there's serial data available
intinByte =Serial.parseInt(); // read it
if(inByte > 0) {
Serial.write(inByte); // send it back out as raw binary data
analogWrite(5, inByte); // use it to set the LED brightness
// if you're using a speaker instead of an LED, uncomment line below and comment out the previous line:
// tone(5, inByte*10); // play tone on pin 5
}
}
}
Upload this to your microcontroller, then open the Serial Monitor and send in some ASCII numeric strings. You’ll see the character that’s represented by the string’s value. For example, 65 will return A, 34 will return “, and so forth.Notice that this version of the sketch has a conditional statement to check if the incoming byte is 0. This is because of a quirk of the parseInt() function. It returns 0 if the timeout is hit, or if the string is legitimately 0. This means you can’t really parse for a string like this: "0\n".
Program p5.js To Send a String
Now that your microcontroller is expecting a string, program P5.js to send one. This means changing the mouseDragged() function. Program it to print a string with a newline at the end using the serial.println() command like so:
1
serial.println(outByte);
Since the newline added at the end by serial.println() is a non-numeric character, the Serial.parseInt() function will see it and parse the string, not waiting for the timeout.
To see the sketch running on GitHub at this link. You can see the source files for copying into the p5.js editor at this link.
Conclusion
When you’re sending data between two computers using asynchronous serial communication, you have to make sure that what the sender is sending is formatted the same as what the receiver is listening for. See Table 1 to review what are suitable data formats for different types/sizes of data and which functions to use on p5.js and Arduino for serial communication.
Number of Bytes
1 Byte
Multi Bytes
Data to Send
A single number < 255
A single character
A single number > 255, multiple values
Send as:
Binary
Ascii
Ascii
p5.js ->
serial.write(integer)
serial.write(string)
serial.write
(valueToSend + ",")
-> Arduino
Serial.read()
Serial.parseInt()
Table 1. Serial Communication: p5.js to Arduino
Think this out in advance before you code, then consider what functions you’ve got on both computers to convert data from strings to raw binary numbers and back. Test with fixed values at first, so you know you’re getting what you think you should. For example, sending an ASCII-encoded numeric string like this:
1023\n
Will always result in these six bytes:
49 48 50 51 10
Likewise, this text string:
Hello\n
will always be:
72 101 108 108 111 10
By sending a string you know both the ASCII and raw binary representations of, you can test your code easier, because what you’re sending won’t change. Once you know the sending and receiving works, then you can send variable strings.
The more you work with serial data, the more you’ll become familiar with the methods for handling it.
This lab uses a p5.js library called p5.WebSerial to make it easy in p5.js. In this lab, you’ll generate an analog output value from a potentiometer, then send that value via asynchronous serial communication to P5.js. You’ll use that value in P5.js to draw a graph.
Web browsers have traditionally been designed to be separate from the rest of a computer’s operating system, not able to connect to the computer’s hardware ports for security reasons. Recently, however, the W3C developed the WebSerial API in JavaScript, which allows browsers to communicate with a computer’s serial ports. WebSerial is currently only available in the Chrome and Chromium browsers and the Microsoft Edge browser, so make sure you’re using one of those to do this lab.
To get the most out of this tutorial, you should know what a microcontroller is and how to program them. You should also understand asynchronous serial communication between microcontrollers and personal computers. You should also understand the basics of P5.js.
Once you gain an understanding of serial communication, you can use any program that can connect with your computer’s serial ports to communicate with a microcontroller. In addition to the WebSerial API you’ll see here, you can use other programming environments to communicate serially. Processing, Max/MSP, and OpenFrameworks are three other popular multimedia programming environments that can communicate via the serial ports. You can also do this with Unity, Unreal, or any other programming environment that can access the serial ports.
Figures 1-4 below show the parts you’ll need for this exercise. Click on any image for a larger view.
Figure 1. Microcontroller. Shown here is an Arduino Nano 33 IoT
Figure 2. Jumper wires. You can also use pre-cut solid-core jumper wires.
Figure 3. A solderless breadboard
Figure 4. Potentiometer
Prepare the Breadboard
For this exercise you’re going to attach a potentiometer as an analog input to your microcontroller, and send the sensor’s reading serially to p5.js via the p5.serialcontrol app.
Connect power and ground on the breadboard to the microcontroller. On the Arduino module, use the 5V or 3.3V (depending on your model) and any of the ground connections. Figures 5 and 6 show connections for an Arduino Uno and a Nano, respectively.
Figure 5. An Arduino Uno on the left connected to a solderless breadboard, right.
The Uno’s 5V output hole is connected to the red column of holes on the far left side of the breadboard (Figure 5). The Uno’s ground hole is connected to the blue column on the left of the board. The red and blue columns on the left of the breadboard are connected to the red and blue columns on the right side of the breadboard with red and black wires, respectively. These columns on the side of a breadboard are commonly called the buses. The red line is the voltage bus, and the black or blue line is the ground bus.
Figure 6. Breadboard view of an Arduino Nano mounted on a breadboard.
Images made with Fritzing, a circuit drawing application
The Nano is mounted at the top of the breadboard (Figure 6), straddling the center divide, with its USB connector facing up. The top pins of the Nano are in row 1 of the breadboard.
The Nano, like all Dual-Inline Package (DIP) modules, has its physical pins numbered in a U shape, from top left to bottom left, to bottom right to top right. The Nano’s 3.3V pin (physical pin 2) is connected to the left side red column of the breadboard. The Nano’s GND pin (physical pin 14) is connected to the left side black column. These columns on the side of a breadboard are commonly called the buses. The red line is the voltage bus, and the black or blue line is the ground bus. The blue columns (ground buses) are connected together at the bottom of the breadboard with a black wire. The red columns (voltage buses) are connected together at the bottom of the breadboard with a red wire.
Add a Potentiometer
Connect a potentiometer to analog in pin 0 of the module. Figure 7 shows the schematic and figures 8 and 9 show the potentiometer connected to an Arduino and Nano, respectively.
Figure 7. Schematic view of a potentiometer connected to analog in 0 of the Arduino
Figure 8. Breadboard view of a potentiometer connected to analog in 0 of an Arduino. The potentiometer is connected to three rows in the left center section of the breadboard. The two outside pins are connected to voltage and ground. The center pin is connected to the Arduino’s analog in 0.
Figure 9. Breadboard view of a potentiometer connected to analog in 0 of an Arduino Nano. The Nano is connected as usual, straddling the first fifteen rows of the breadboard with the USB connector facing up. Voltage (physical pin 2) is connected to the breadboard’s voltage bus, and ground (physical pin 14) is connected to the breadboard’s ground bus. The potentiometer is connected to three rows in the left center section of the breadboard. The two outside pins are connected to voltage and ground. The center pin is connected to the Nano’s analog in 0.
Program the Microcontroller
Program your Arduino to read the analog input as follows:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
voidsetup() {
Serial.begin(9600); // initialize serial communications
As you work on this any microcontroller-to-computer application, you will be switching back and forth between the app that programs the microcontroller (in this case, the Arduino IDE) and the app that the microcontroller is communicating with (in this case, p5.js in the browser). You have to keep in mind that only one of these at a time can access a serial port.
That means that when you want to reprogram your Arduino from the Arduino IDE, you should to stop your sketch in the browser window to do so. Then, restart the browser sketch when you’re done reprogramming the Arduino. You don’t need to quit the Arduino IDE each time, because it knows to release the serial port when it’s not programming. However, you do need to close the Serial Monitor in the Arduino IDE when you are using WebSerial in the browser.
The P5.js WebSerial Library
To communicate with your microcontroller serially, you’re going to use the P5.js WebSerial library. If you’re using the p5.js web editor, make a new sketch. Click the Sketch Files tab, and then choose the index.html file. In the head of the document, look for this line:
To start off, you need to know if WebSerial is supported in the browser you’re using. Open the sketch.js file and change it to the following:
1
2
3
4
5
6
7
8
9
// variable to hold an instance of the p5.webserial library:
const serial = newp5.WebSerial();
functionsetup() {
// check to see if serial is available:
if(!navigator.serial) {
alert("WebSerial is not supported in this browser. Try Chrome or MS Edge.");
}
}
When you run this p5.js sketch in a browser, you’ll get a message letting you know whether or not this browser supports WebSerial. In a browser that supports WebSerial, you may want to delete the else clause.
Serial Events
JavaScript, the language on which p5.js is based, relies heavily on events and callback functions. An event is generated by the operating system when something significant happens, like a serial port opening, or new data arriving in the port. In your sketch, you write a callback function to respond to that event. The p5.webserial library uses events and callback functions as well. It can listen for the following serialport events:
noport – when there is no selected serial port
portavailable – when a serial port becomes available
data – new data arrives in a serial port
close – the serial port is closed
requesterror – something goes wrong when you request a serial port.
The WebSerial API on which the p5.webserial library is based also has connect and disconnect events for when a serial port is physically disconnected (or in the case of a USB-native device like the Nano 33 IoT, when it is reset). You’ll see those below as well, and you’ll see them run whenever the serial connection to the Arduino is reset.
To use the the webserial library’s events, you need to set callback functions for them. Change your sketch to include a port chooser button and a variable for incoming data, then in the setup() function, add callbacks for open, close, and data, and error like so:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// variable to hold an instance of the p5.webserial library:
const serial = newp5.WebSerial();
// HTML button object:
letportButton;
letinData; // for incoming serial data
letoutByte = 0; // for outgoing data
functionsetup() {
createCanvas(400, 300); // make the canvas
// check to see if serial is available:
if(!navigator.serial) {
alert("WebSerial is not supported in this browser. Try Chrome or MS Edge.");
}
// if serial is available, add connect/disconnect listeners:
The draw() function is empty for the moment. You’ll come back and fill that in later.
Now that you’ve set listeners for the events, you need to add the callback functions. Here they are. Add these after the draw() function:
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
// if there's no port selected,
// make a port select button appear:
functionmakePortButton() {
// create and position a port chooser button:
portButton = createButton("choose port");
portButton.position(10, 10);
// give the port button a mousepressed handler:
portButton.mousePressed(choosePort);
}
// make the port selector window appear:
functionchoosePort() {
if(portButton) portButton.show();
serial.requestPort();
}
// open the selected port, and make the port
// button invisible:
functionopenPort() {
// wait for the serial.open promise to return,
// then call the initiateSerial function
serial.open().then(initiateSerial);
// once the port opens, let the user know:
functioninitiateSerial() {
console.log("port open");
}
// hide the port button once a port is chosen:
if(portButton) portButton.hide();
}
// pop up an alert if there's a port error:
functionportError(err) {
alert("Serial port error: "+ err);
}
// read any incoming data as a string
// (assumes a newline at the end of it):
functionserialEvent() {
inData = Number(serial.read());
console.log(inData);
}
// try to connect if a new serial port
// gets added (i.e. plugged in via USB):
functionportConnect() {
console.log("port connected");
serial.getPorts();
}
// if a port is disconnected:
functionportDisconnect() {
serial.close();
console.log("port disconnected");
}
functionclosePort() {
serial.close();
}
Wait a Minute! Don’t I have to Set the Data Rate When I Open the Port?
In asynchronous serial communications, both computers have to set the same data rate in order to communicate. In Arduino, you set the data rate with Serial.begin(9600); In p5.webserial, 9600 bits per second is the default, so you don’t have to set the rate if you want 9600bps. But if you want to set the rate to another value, change your serial.open() call in the openPort() function as follows:
1
2
letoptions = { baudrate: 9600}; // change the data rate to whatever you wish
serial.open(portName, options);
There are other port options you can set using p5.webserial, including baudRate, bufferSize, dataBits, flowControl, parity and stopBits. These are all standard serialport options, and most programming environments which support serial communication will have them. You can get details of these in the p5.webserial documentation.
p5.WebSerial Sketch Checklist
Most p5.WebSerial sketches that you write will have a similar structure to this one. The main difference between them all will be how you read and interpret incoming serial data, and how and when you send and format outgoing serial data. Here’s a checklist of the pieces you’re likely to see in every sketch:
In the HTML file, include the p5.webserial library
In the global variables of the sketch,
make a new instance of the library
include a port selector button or some way to invoke the serial port chooser dialogue box
In the setup:
Make sure WebSerial is supported in this browser
Include a call to serial.getPorts() to check for available ports.
include serial.on() listeners for these events:
noport
portavailable
data
close
requesterror
include navigator listeners for connect and disconnect
Define handler functions for all of the events above. Most of these can be simple alerts or console.log messages
Customize the function that responds to the data listener (usually called serialEvent() in these examples), as you’ll see below.
Decide when and how you’ll send serial data out, as you’ll see in the other p5.webserial labs.
The last two items of this list are the ones on which you’ll spend most of your time. The rest of the items are things you’re likely to copy from one sketch to another.
Reading Incoming Serial Data
The event that that you’ll use the most is the data event, which calls the serialEvent() function. Each time a new byte arrives in the serial port, this function is called. Now it’s time to make serialEvent() do some work. Add a new global variable at the top of your sketch called inData like so:
The serialEvent() function you added above looks like this:
1
2
3
4
functionserialEvent() {
inData = Number(serial.read());
console.log(inData);
}
It’s reading the incoming data byte by byte, and interpreting each byte as a number. That’s why the Number() function surrounds the read() function. Since you’re sending the data from the Arduino as a binary value (using the Serial.write() function), you have to interpret it in p5.js as a binary value as well.
Next, make the draw() function to print the sensor value to the screen like so:
1
2
3
4
5
functiondraw() {
background(0);
fill(255);
text("sensor value: "+ inData, 30, 50);
}
Figure 10. A screenshot of the sketch running in a browser. The sketch prints the sensor value in text on the screen.
When you run your sketch now, you should get something like the sketch shown in Figure 10.
To see the sketch running on GitHub at this link. You can see the source files for copying into the p5.js editor at this link.
The sensor value onscreen should change as you turn your potentiometer. Congratulations! You’ve got P5.js talking to your microcontroller.
What’s Happening Here
Every time your microcontroller sends a byte serially using Serial.write(), the computer receives it and generates a ‘data’ event. Then your serialEvent() function is called. It reads the byte as a number, and stores it in the global variable inData. The draw() method just uses the latest value of inData in the text string it displays on the screen.
You may be wondering why you’re mapping the sensor value or dividing it by 4 in the Arduino sketch above. That’s because in order to send the sensor value as a single byte, it must be between 0 and 255, or no more than 28 bits.
P5.js Console.log() and Arduino delay(): a Tricky Combination
In testing this, you may have put a console.log() statement in the serialEvent() function in your P5.js sketch. When you did, you would have noticed that it causes a lag in the sketch, and the console.log() statements continue even after you stop the sketch. This is because the operating system keeps the incoming serial data in a buffer, and P5.js isn’t reading and printing it as fast as Arduino is sending it.
You might think, “Okay, then I’ll just put a delay() in my Arduino sketch to slow it down.” That’s a bad idea. When you put in a delay, it means you’re only reading your sensor when that delay is not running. You can miss critical sensor events while that delay is in progress. Even a relatively small delay, for example 30ms, can make it difficult to reliably read state changes in a switch or peaks in an analog sensor. Don’t use delays if you can avoid it. For more on how to handle the flow of serial data from Arduino to P5.js and back, see the Duplex Serial Flow using WebSerial in P5.js lab.
Draw a Graph With the Sensor Values
It would be useful to see a graph of the sensor values over time. You can do that by modifying the draw() method to draw the graph. To do this, add a new global variable at the top of your sketch called xPos. You’ll use this to keep track of the x position of the latest graph line:
1
letxPos = 0; // x position of the graph
Because of the way the graphing function below works, you can’t reset the background every time through the draw() loop. So take the background() command and put it in the setup() function instead of the draw(), as shown below. That way it runs once, then not again. As long as you’re at it, switch from black & white to a nice blue color:
1
2
3
functionsetup() {
createCanvas(400, 300);
background(0x08, 0x16, 0x40);
Now make a new function called graphData(). It’ll take a number value as a parameter, and it will draw a line on the screen that’s mapped to the number value. Then it will increment xPos so that the next line is drawn further along. It will also check if the xPos is at the right edge of the screen, and reset the screen by calling background() again if it is:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
functiongraphData(newData) {
// map the range of the input to the window height:
varyPos = map(newData, 0, 255, 0, height);
// draw the line in a pretty color:
stroke(0xA8, 0xD9, 0xA7);
line(xPos, height, xPos, height - yPos);
// at the edge of the screen, go back to the beginning:
if(xPos >= width) {
xPos = 0;
// clear the screen by resetting the background:
background(0x08, 0x16, 0x40);
} else{
// increment the horizontal position for the next reading:
xPos++;
}
}
Finally, take everything out of the draw() function and just call graphData() from there:
1
2
3
functiondraw() {
graphData(inData);
}
When you run the sketch now, you should get a graph, as shown in Figure 11.
Figure 11. Screenshot of the serial graph p5.js sketch. The sensor’s values are graphed on the screen
To see the sketch running on GitHub at this link. You can see the source files for copying into the p5.js editor at this link.
Reading Serial Data as a String
This works well if you want to read your sensor values as a single byte, but what if you want a larger range of numbers? What if you want the full 0 to 1023 that analogRead() can output instead of just 0 to 255? To do this, you need to send the data as an ASCII-encoded numeric string from the microcontroller, and you need to read and interpret the incoming data in P5 as an ASCII-encoded numeric string as well.
Change your Arduino program to the following:
1
2
3
4
5
6
7
8
9
10
voidsetup() {
Serial.begin(9600); // initialize serial communications
}
voidloop() {
intpotentiometer =analogRead(A0); // read the input pin
intmappedPot =map(potentiometer, 0, 1023, 0, 255); // remap the pot value to fit in 1 byte
Serial.println(mappedPot); // print it out the serial port
delay(1); // slight delay to stabilize the ADC
}
Now it will print the potentiometer’s value as an ASCII-encoded numeric string, and it will add a carriage return byte and a newline byte at the end, because that’s what println() does.
Once you’ve uploaded this to your Arduino, run your P5 sketch again. Try adding println(inData);at the end of your serialEvent() function. When your P5 sketch reads the data from this Arduino program, you get very low values, and every so often you see the value 10 followed by the value 13. What’s going on?
When a computer ASCII-encodes a number, it converts that number to a string of bytes, each of which is the ASCII value for a numeral in the number. For example, the number 865 gets converted to three bytes, as shown in Figure 12.
Figure 12. The decimal number 865 when sent serially as ASCII is three bytes long. The first byte representing digit, 8, has the ASCII value 58. The second byte representing the digit 6 has the ASCII value 54. The third byte representing the digit 5 has the ASCII value 53.
If there’s a carriage return byte and a newline byte after this, the string is five bytes, and the last two bytes’ values are 13 (carriage return, or \r in most programming languages) and 10 (newline or \n in most programming languages), respectively.
Your P5.js sketch is reading every byte’s value and graphing it. That’s why you get a graph of very low values, with a bunch of them being 13 and 10. The Arduino is ASCII-encoding the potentiometer values, but the P5 sketch is interpreting the bytes as if they’re not encoded that way.
Now change the serialEvent() function like so:
1
2
3
4
functionserialEvent() {
// read a byte from the serial port, convert it to a number:
inData = serial.readLine();
}
Run it again. What’s changed? Now you’re getting a graph kind of like you were before. The serial.readLine();command reads the incoming serial data as a string, and when that string happens to be all-numeric, it converts it to a number. So you’re getting the ASCII-encoded string as a number again. But sometimes there are gaps. Why?
Remember, the ‘data’ event occurs every time a new byte comes in the serial port. Now that you’re sending an ASCII-encoded string, every potentiometer reading is several bytes long. So you only get a complete string every three to six bytes (three for “0\r\n” and six for “1023\r\n”). Sometimes, when the serialEvent() function calls serial.readLine(); it gets nothing. That’s when draw() draws the gaps. You need to change your function to check that the resulting string is actually a valid number before you put the string into inData. First, create a local variable to get the string, then check to see if the string’s length is greater than zero. If it is, then put it into inData so that the other functions in the sketch can use the new data. Here’s how you do that:
1
2
3
4
5
6
7
8
9
functionserialEvent() {
// read a string from the serial port:
varinString = serial.readLine();
// check to see that there's actually a string there:
if(inString) {
// convert it to a number:
inData = Number(inString);
}
}
Now you’re able to send in a number of any value to P5.js. You don’t have to limit your input to a 0-255 value range. See if you can modify the Arduino sketch and the P5.js sketch to exchange a potentiometer value that spans the whole range from 0 to 1023.
note: readLine() is the same as readStringUntil(‘\r\n’);
You can see the sketch running on GitHub at this link. You can see the source files for copying into the p5.js editor at this link.
Conclusion
In this lab, you saw how to connect an Arduino microcontroller to a P5.js sketch using a webSocket-to-serial server, P5.serialserver, and the P5.serialport library. You sent data from Arduino to the sketch as a raw binary value — that is, a single byte ranging from 0 to 255 — and you sent it as an ASCII-encoded numeric string with a carriage return and newline at the end. See Table 1 below to review what are suitable data formats for different types/sizes of data and which functions to use on p5.js and Arduino for serial communication.
Data to Send
A single value
within 0-255
(< 2^8 = 1 byte)
Larger numbers & characters in Ascii Table,
Multiple values
Send as:
Binary
Ascii
Arduino ->
Serial.write()
Serial.println()
-> p5.js
serial.read()
serial.readLine()
=readStringUntil('\r\n')
Table 1. Serial Communication: Arduino to p5.js
Notes about sending ASCII-encoded data:
Using Serial.println() on Arduino and serial.readLine() on p5.js is one of many different ways of sending data from Arduino to p5.js via serial communication.
If you want to read an ASCII-encoded numeric string as a number and not a string, convert the value into number by using Number().
Understanding the difference between ASCII-encoded strings and raw binary data is central to all serial communications. For more examples of this in action, see the WebSerial Output from P5.js lab.
Asynchronous serial communication is not part of the core of p5.js, nor is it part of the core for web browsers. To read serial in a p5.js sketch, or in a web page in general, you need some help. One approach is to open a separate application that connects to the serial port and offers a webSocket connection to the browser. This is the approach that the p5.serialport library and the p5.serialcontrol app take. Another approach is to use the browser API called WebSerial. This is the approach that the p5.webserial library takes.
The difference between them is best illustrated by Figures 1 and 2 below. With p5.seriaport, you must open another application on your computer, p5.serialcontrol, to communicate with the serial port. It is this application that handles serial communication, not the p5.js sketch in the browser. This can be more complicated for beginning users.
Figure 1. Diagram of the connection from the serial port to p5.js through p5.serialcontrol
Figure 2. Diagram of the connection from the serial port to p5.js through p5.webserial
p5.serialport/p5.serialcontrol:
p5.webserial:
advantages: * works in all browsers. * Allows your browser to connect to the serial port of a remote computer, if that computer is running a web server program. * Supports opening multiple serial ports at the same time
advantages: * connection is direct to the browser, making it easier for beginners to learn
disadvantages: * requires a third application (p5.serialcontrol), making it more difficult for beginners to learn
disadvantages: * only works in Chrome and Edge browsers * No connection to remote computers * Not sure if it supports a second serial port.
Table 1. Comparing p5.seriaport to p5.webserial
The APIs of p5.serialport and p5.webserial are similar, so it’s pretty straightforward to convert between them.
The code below is a typical p5.serialport setup. You make an instance of the p5.serialport library with the port name, then you make callback functions for the primary tasks:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
letserial; // variable to hold an instance of the serialport library
letportName = '/dev/cu.usbmodem1421'; // fill in your serial port name here
functionsetup() {
serial = newp5.SerialPort(); // make a new instance of the serialport library
serial.on('list', printList); // set a callback function for the serialport list event
serial.on('connected', serverConnected); // callback for connecting to the server
serial.on('open', portOpen); // callback for the port opening
serial.on('data', serialEvent); // callback for when new data arrives
serial.on('error', serialError); // callback for errors
serial.on('close', portClose); // callback for the port closing
serial.list(); // list the serial ports
serial.open(portName); // open a serial port
}
The code below is a typical p5.webserial setup. You check t see if WebSerial is available, and then you make an instance of the p5.webserial library, then you look for ports using getPorts():
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// variable to hold an instance of the p5.webserial library:
const serial = newp5.WebSerial();
// port chooser button:
letportButton;
// variable for incoming serial data:
letinData;
functionsetup() {
// check to see if serial is available:
if(!navigator.serial) {
alert("WebSerial is not supported in this browser. Try Chrome or MS Edge.");
}
// check for any ports that are available:
serial.getPorts();
// setup function continues below:
Unlike with p5.serialport, you don’t pass in the port name. Instead, the user chooses the port with a pop-up menu:
1
2
3
4
5
// if there's no port chosen, choose one:
serial.on("noport", makePortButton);
// open whatever port is available:
serial.on("portavailable", openPort);
// setup function continues below:
Then you make callback functions for the primary tasks. These are similar to p5.serialport’s callbacks:
1
2
3
4
5
6
// handle serial errors:
serial.on("requesterror", portError);
// handle any incoming serial data:
serial.on("data", serialEvent);
serial.on("close", makePortButton)
// setup function continues below:
You also add listeners for when the USB serial port enumerates or de-enumerates. This way, if you unplug your serial device or reset it, your program automatically reopens it when it’s available:
1
2
3
4
// add serial connect/disconnect listeners from WebSerial API:
read() returns a single byte of data (first in the buffer)
read() — reads a single byte from the queue (returns a number)
readChar() returns a single char, e,g, ‘A’, ‘a’
readChar() — reads a single byte from the queue as a character (returns a string)
readBytes() returns all of the data available as an array of bytes
readBytes() — reads all data currently available in the queue as a Uint8Array.
readBytesUntil(charToFind) returns all of the data available until charToFind is encountered
readBytesUntil(charToFind) — reads bytes until a character is found (returns a Uint8Array)
readString() returns all of the data available as a string
readStringUntil(charToFind) returns all of the data available as a string until charToFind is encountered
readStringUntil(stringToFind) — reads out a string until a certain substring is found (returns a string)
last() returns the last byte of data from the buffer
lastChar() returns the last byte of data from the buffer as a char
readLine() — read a string until a line ending is found (returns a string)
write() – sends most any JS data type out the port.
write() – sends most any JS data type out the port.
print()– sends string data out the serial port
println() – sends string data out the serial port, along with a newline character.
Table 2. Comparison of p5.serialport and p5.webserial APIs
Both p5.serialport and p5.webserial will do the job of getting bytes from a serial device like an Arduino or other microcontroller to p5.js and vice versa. Which you use depends on what you need. p5.webserial is great if you’re connected directly to the browser’s computer via USB. For most serial applications, this is the way to go. Alternately, p5.serialport offers the advantage that you can run p5.serialcontrol app on your browser’s computer or on another computer on the same network. That way, a browser on your phone or tablet can communicate to the serial device via the computer running p5.serialcontrol.
Many common electronic devices feature small screens for status updates, control feedback, and so forth. These displays feature many different technologies. Lately, one of the most common is the OLED display. These displays are matrices of organic LEDs, each pixel being comprised of one to three LEDS. Small displays typically use either the SPI or I2C synchronous serial protocols. In this lab, you’ll use I2C to control a monochrome OLED display with an array of 128×64 OLEDs to display text and monochrome graphics. The Solomon Systech SSD1306 OLED driver IC is a popular and inexpensive display driver in lots of display breakouts.
a potentiometer. You can use any analog sensor you choose, however.
an SSD1306 OLED breakout board
There are many breakout boards that use the SSD1306 OLED: Adafruit, Sparkfun , DFRobot, Crystalfontz, MakerFocus, Amazon, and many others. It typically comes in a 128×32 pixel version and a 128×64 pixel version. Solomon Systech makes other variations on this display as well, like the SSD1309 or the 1315. They come with different resolutions, different physical sizes, and different features.
Most of the SSD1206 displays have all blue pixels, but there are some models on the market have one section of yellow pixels and the rest blue. You can’t change the color of the pixels, so be aware of what you are buying and choose what you need. If you need a board with all blue pixels, don’t get the one with the yellow section.
Connect the display’s voltage and ground pins to your voltage and ground buses, and the I2C clock (SCL) and I2C serial data (SDA) pins to your microcontroller’s corresponding I2C pins as shown in Figure 6-7. The schematic, Figure 6, is the same for both the Uno and the Nano. For the Arduino Uno or the Arduino Nano boards, the I2C pins are pins A4 (SDA) and A5(SCL). This is the same connection for almost any I2C device.
Connect the potentiometer’s two outside connections to power and ground, respectively. Connect the middle pin (the wiper) to the Arduino’s pin A0. You’ll use the potentiometer to generate something to display on the screen.
Once you’ve got the circuit wired as shown in Figures 6-7, you’re ready to program the microcontroller.
Figure 6. Breadboard view of a potentiometer and an SSD1306 OLED screen attached to a Nano 33 IoT. The potentiometer is connected to pin A0. The screen’s SDA pin is connected to pin A4 and the SCL pin is connected to pin A5.
Figure 7. Schematic drawing of a potentiometer and an SSD1306 OLED screen attached to a Nano 33 IoT. The schematic is the same for an Uno. The potentiometer is connected to pin A0. The screen’s SDA pin is connected to pin A4 and the SCL pin is connected to pin A5.
Program the Microcontroller
There are many libraries available for controlling the SSD1306 OLED screens. Adafruit’s SSD1306 library works well with all the SSD1306 displays, both the 128×64 and 128×32 models. Adafruit’s library is consistent with many of their other display libraries, and they make a lot of them. So it’s a good place to start. It doesn’t work with other SSD13xx models though. For example, Sparkfun makes a Micro OLED with the SSD1309, which has a 64×48 resolution. It requires a different library.
The u8g2 library by Oli Kraus, is intended as a universal monochrome display library for OLED, eInk, TFT, and other displays. It supports some SSD130x boards, but not all. It’s a pretty good library, but lacks some of the features of the Adafruit library. The examples included here use the Adafruit library. You’ll also need the Adafruit_GFX library which supports graphics across a number of small displays.
Import the Libraries
At the start of your sketch, import the libraries and set up a variable to hold the display driver instance like so:
1
2
3
4
5
6
7
8
9
#include<Wire.h>
#include<Adafruit_SSD1306.h>
#include<Adafruit_GFX.h>
constintSCREEN_WIDTH =128; // OLED display width, in pixels
constintSCREEN_HEIGHT =64; // OLED display height, in pixels
In the setup, you need to check that the display is working. If it fails, it’s a good idea to stop and notify the user. Since there’s no user interface in this basic sketch, you’ll use the Serial Monitor.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
voidsetup() {
// initialize serial and wait for serial monitor to open:
Serial.begin(9600);
if(!Serial) delay(3000);
// first parameter of begin() sets voltage source.
// SSD1306_SWITCHCAPVCC is for 3.3V
// second parameter is I2C address, which is
// 0x3C, or 3D for some 128x64 modules:
if(!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
Serial.println("Display setup failed");
while(true);
}
Serial.println("Display is good to go");
}
Print to the Display
You can print to the display by giving it a text size and cursor position and then using .print() or .println(). The loop below reads analog input 0, then prints the time in seconds on the first line and the sensor reading on the second.
The function which actually updates the display is called .display(). All of the other functions update a buffer in the microcontroller’s memory. So you can make all the changes you want with commands like .print(), .setCursor(), .clearDisplay(), and so forth, but you will only see the changes when you call .display(). This is typical of many display libraries.
In the code below, you’ll clear the display, then set the size to twice the default, then move the cursor to the top left. Then you print the seconds since the sketch started, move the cursor down a line, and print the analog 0 sensor reading. Finally, you push it all to the display using .display():
The SSD1306 is a monochrome display, but you still have to set the color to see anything display, because the library defaults to no colors. For a list of what SSD1306_WHITE and the other constants in the library mean, see this link.
Fonts
The default font of the library is not terribly attractive, and gets blocky when you increase the size. But you can add fonts. The Adafruit_GFX library includes many fonts compatible with lots of their display libraries. Search for this library in the library manager and include it to use the fonts. They have a good tutorial on using fonts as well. The short version is as follows. First, include the font you want to use with your library includes like so:
1
#include<Fonts/FreeSans9pt7b.h>
Next, in your setup() or whenever you want to switch fonts, use the .setFont() function like so:
One of the nice things about using custom fonts is if you pick the right size for your screen, you don’t need to use .setTextSize(), so you can avoid pixelating your font. Note that custom fonts generally measure pixel height from the baseline. So, to position a 16-point font at the top of the screen, for example, position it with a few pixels at the top to spare: at (0, 20), not (0,0).
You can also use more custom fonts by generating them from this OLED display custom font generator. For “Library Version” choose “Adafruit GFX Font”. This will generate a custom header file that you include with your sketch. Make a new tab in the IDE, give the tab a name like font.h, and include it at the top of your code with the other library header files. The font name will be at the bottom of the header file. For example, if you generated the Dialog Font, Plain, 16 point, the font name would be Dialog_plain_16 and you’d include it just like the one above, like so:
There are many libraries for graphics on small displays. Typically these displays don’t have a fast refresh rate, so you can’t exactly create fast action games on them, but they can be good for simple graphic informational displays. Different display libraries will have slightingly different naming schemes for their graphics, but you can usually count on being able to draw points, lines, rectangles, circles, and sometimes rounded rects and triangles. You can generally also count on functions like drawRect() vs. fillRect() depending on whether you want a filled rectangle or not. All libraries will include methods for setting a color, clearing a screen, and filling the screen with a color. Most will also include commands for rotating the graphics display. Here’s the Adafruit_GFX library graphics primitives tutorial as an example.
Remember, all of your commands are only executed when you call .display().
One way you can use the graphic capabilities of any small display is to show QR codes. QR codes can contain any string of text you want in a machine-readable form. Though we’re used to generating QR codes to supply web addresses (URLs), you can also send plain text strings, phone numbers, passcodes or other test-based information as well. On microcontroller-based devices, they can be a way to transfer identifying information like IP or MAC addresses, Bluetooth LE service UUIDs, or anything else your mobile phone or tablet might need to know about your microcontroller device in order to communicate with it.
QR codes can be generated from a text string and translated to a microcontroller display using Richard Moore’s qrcode library for Arduino and the graphics library for your particular display.
Like any library, you need to include the qrcode library at the top of your code like so:
1
#include<qrcode.h>
Determining QR Code Block Size
A QR code’s block size is the height and width of each of the blocks in the code. It depends size depends on the number of blocks per side. The length of the string you plan to display and a few other factors affect the block size. Here’s a table which lays out how the string length, error correction, and QR code version affect the the pixel dimensions of a QR code. Here’s a simpler version in the documentation for the qrcode library. A long string or higher levels of error correction can result in largee QR codes than you can fit on a small display. The library’s .size() function can give you the number of blocks in your QR code.
QR Codes need a “quiet zone” around the block in order to be readable to another device, so you can’t fill your display’s entire length or width with a QR code.
Here’s a good rule of thumb to get a block size that you can fit on your display:
Set the QR version and the QR error level
Start with an arbitrary offset. The larger your offset, the smaller the QR code can be.
Subtract twice the offset width (also arbitrary) from the display’s smallest dimension (64px, in the case of the SSD1306)
divide by the qrcode.size
Here’s a function to generate a QR code. It will take a String object, the QR code version you want to use, and the QR code error level you want, then it will generate a QRCode object, and display it on the display using the display library’s .fillRect() function:
// refresh the display here, after the nested loops:
display.display();
// print the message:
Serial.println(message);
}
Here’s a link to a full sketch to generate QR codes on an SSD1306 display. Upload it to your Nano, then open the serial monitor and enter a string to display. Then scan the QR Code with your phone’s QR scanning app. You should be able to read short strings of text, up to 50 or so characters. You can also send URLs, phone numbers, or anything else your phone’s QR code reader can interpret.
The shorter the string, the easier it is for your QR code scanner to read it. This is why many URLs you see on QR codes in public use URL shorteners.
Conclusion
Even though the SSD1306 is a small, low resolution monochrome display, it packs a lot of potential for the price. Adding an informational display can improve many devices, and by adding a QR code, you have the possibility to add many more features through the web, Bluetooth, and more. For more on microcntroller displays, see this repository.
Playback of digital sound files is a popular use of microcontrollers. The Inter-IC Sound (I2S) protocol makes this possible. In this lab, you’ll learn how to use the I2S bus on the Arduino Nano 33 IoT in combination with the SPI bus to read a .wav sound file from a microSD card and play it on an I2S-compatible amplifier.
What is I2S?
I2S, the Inter-IC Sound protocol, is a serial protocol used for connecting digital audio devices. I2S allows you to transmit Pulse-Code Modulated (PCM) audio data between integrated circuits, like a microcontroller and a digital amplifier. The Arduino site offers a brief introduction to I2S, and Wikipedia has a good definition page on I2S as well. Though it’s not the only means of transmitting digitized audio from one component to another, it is a popular one.
Don’t confuse I2S with I2C, the inter-integrated circuit protocol. Both are synchronous serial protocols, but with different purposes. You can learn about I2C in these labs.
This will not work on the Uno. It will only work on the Nano 33 IoT and the MKR series Arduino boards, which have an I2S bus built in. The Arduino I2S and the ArduinoSound libraries support I2S.
Figure 4. A MicroSD breakout board and MicroSD card.
Figure 5. I2S Audio amp. The UDA1334 breakout board from Adafruit has been tested with this lab.
Figure 6. I2S Audio Amp. The MAX98357A amp breakout board from Sparkfun has been tested with this lab. Wires have been soldered to the Audio out + and – pins to make it easier to connect. Click to see the full part.
Figure 7. 3.5mm audio jack. If you use the MAX98357A amp, you’ll need a jack as well.
Figure 8. If you’re using the MAX98357A amp, you can use a speaker as an alternative for the phono jack.
The Circuit
The circuit for this lab consists of:
the microcontroller
a microSD card breakout
an I2S audio amp breakout.
You’ll also need a microSD card reader for your personal computer.
The lab has been tested with two different amps, the UDA1334 breakout board from Adafruit, and the MAX98357A breakout board from Sparkfun. Both work just the same, but the Sparkfun amp needs an additional component, a 3.5mm audio hack.You’ll need to attach wires to connect to a stereo mini jack, as shown here, or you’ll need to solder a speaker onto the + and – holes of the breakout board. The Adafruit board has a built-in jack.
Connect the SD Card Breakout Board
The microSD card in this lab is for storing the .wav files that you want to play. You can playback from multiple files with the libraries used in this project.
SD cards use the Serial Peripheral Interface (SPI) protocol to communicate with microcontrollers and other computers. SPI is a synchronous serial protocol that supports two-way communication between a controller device such as a microcontroller and a peripheral device like an SD card reader. All SPI devices have a common set of connections:
a Serial Data In (SDI) connection, on which the controller sends data to the peripheral devices.
a Serial Data Out (SDO) connection, on which the peripheral devices send data to the controller.
a SerialClock (SCLK) connection, on which the controller sends a regular clock signal to the peripheral devices.
one or more Chip Select (CS) connections, which the controller uses to signal the peripheral devices when to listen to incoming data and when to ignore it.
The SDO of a controller connects to the SDI of a peripheral, and vice versa.
The SPI pin numbers are the same numbers for the Uno and Nano 33 IoT, as follows:
SDO – pin 11
SDI – pin 12
SCK – pin 13
CS – pin 10
The MicroSD card reader/writer shown in Figure 4 is from Sparkfun. It has level-shifting circuitry built-in to adjust for either 3.3- or 5-volt operation. They have a second model which is shown in Figure 9 was the model for the breadboard drawing in Figure 10. Both will work with this lab. There are many other models on the market though. Here’s an Adafruit model. Here’s a Pololu model. Here’s a DFRobot model. All of them will communicate with your microcontroller in basically the same way, though, using the SPI pin connections.
Most SD card readers have a card detect (CD) pin as well, that changes state when the card is inserted or removed. It’s optional, but it can be useful to make sure you have a card in the reader. It’s not used in this example. You will see differing names for the SPI pins as the names as manufacturers modernize their naming conventions. As a result, different breakout boards may have different labels. Make sure to match up the pin functions, not just the pin numbers. Figure 9 shows several models, and you can see that the pin naming conventions and pin positions differ from one model to the next.
Figure 9. Different microSD breakout boards have different arrangements of the pins and different naming conventions. Shown here, from left to right: A Pololu MicroSD card breakout board; An Adafruit one; a Sparkfun one; and a DFRobot one.
Connect your Arduino to the SD card reader as shown in Figure 10 and 11. If you’re using the Sparkfun SD card reader/writer, the pins are on the on the left side of the board, and they’re numbered, from top to bottom, as follows:
Vcc – voltage in. Connects to microcontroller voltage out
CS – Chip select. Connects to microcontroller CS (pin D10 on the Nano/Uno)
DI – SPI data in. Connects to microcontroller SDO (pin D11 on the Nano/Uno)
SCK – SPI clock.. Connects to microcontroller SCLK (pin D13 on the Nano/Uno)
DO – SPI data out. Connects to microcontroller SDI (pin D12 on the Nano/Uno)
CD – card detect. Not connected in this example
GND – ground. Connects to microcontroller ground
Figure 10. Schematic drawing of a microSD card reader attached to an Arduino using SPI connections
Figure 11. Schematic drawing of a microSD card reader attached to an Arduino using SPI connections
Connect the I2S Amplifier
The I2S amplifier takes the digitized audio signal from your microcontroller and converts it to an analog audio signal that can play on analog speakers or headphones. The connections for an I2S bus are:
Serial clock (SCK) or Bit Clock (BCLK) – This is the line that carries the clock signal
Frame Select (FS), also called Word Select (WS or WSEL), or Left-Right Clock (LRC) – This determines left and right channels
Data, also called Digital Out (DOUT) or Digital In (DIN) depending on the application – This is the data signal itself.
The controlling device sends the clock signal, just like in other synchronous serial protocols like I2C and SPI.
Connect the I2S amp to your Arduino as follows:
BCLK connects to A3 of the Nano 33 IoT board
LRC connects to A2 of the Nano 33 IoT board
DIN connects to D4 (SDA Pin) of the Nano 33 IoT board
Vin connects to 3.3V
GND connects to ground
+ connects to the left and right sides of a 3.5mm audio jack
– connects to the center pin of a 3.5mm audio jack
This wiring is shown in Figures 12 and 13 with a MAX98357 I2S audio amplifier and audio jack. You have to attach a 3.5mm audio jack to the amplifier separately. The photo in Figure 6 shows a jumper wire cut in half and soldered to the + and – terminals of the audio amplifier to make it easier to connect to a 3jack via a breadboard.
Figure 12. Breadboard view of an Arduino Nano 33 IoT connected to a microSD card and MAX98357A I2S amp and audio jack as described above.Figure 13. Schematic view of an Arduino Nano 33 IoT connected to a microSD card and MAX98357A I2S amp and audio jack as described above.
The connections for the Adafruit UDA1334 I2S amp are similar, but the pins have different names:
BCLK connects to A3 of the Nano 33 IoT board
WSEL connects to A2 of the Nano 33 IoT board
DIN connects to D4 (SDA Pin) of the Nano 33 IoT board
Vin connects to 3.3V
GND connects to ground
The UDA1334 amp has a built-in 3.5mm audio jack, so there’s no need to wire a separate jack as there is with the previous amp.
Once you’ve connected the MicroSD card and amplifier, your circuit is ready.
Format the MicroSD card
Your SD card needs to be formatted as FAT32 or FAT16. The SD Card Lab has notes on how to do this. There are also instructions on the Arduino site on formatting your card, as well as the Adafruit site. If you’re formatting on MacOS, you can use the DiskUtility app, but you must format your disk as MS-DOS (FAT). You should test the SD card for reading and writing first.
Your filename needs to correspond to 8.3 naming, so it should be no more than 8 characters long, with the extension .wav at the end.
Make A .WAV file
The ArduinoSound library can only play audio files formatted as .wav files, because these are uncompressed audio files. The .wav file must be formatted as stereo, signed 16-bit, 44100Hz. There’s a good tutorial on the Arduino site on how to do this using the free audio editing software Audacity. Once you’ve made your file, copy it to the SD card.
Program the Microcontroller
The ArduinoSound library comes with a and example called WavePlayback to get you started. Here are a few of the important parameters you should know about:
You’ll make an instance of the SDWaveFile class to read the file from the SD card. From that, you can get the file duration, sample rate, bits per sample, channels, current time, and more. It’s useful to print out one of these properties, like the file duration, when you open it, to see that things are working.
The AudioOutI2S class gives you control over playback. You can check if the output can play, and you can play, pause, loop, resume, stop the playback. You can also check whether the file is playing or paused and you can set the volume.
Import the Library
Download the ArduinoSound library on your Arduino IDE. You can find it in the Library Manager of the IDE (Sketch Menu -> Include Library -> Manage Libraries, search for “ArduinoSound”). At the start of your sketch, import the libraries and set up a variable to hold the SDWaveFile instance like so:
1
2
3
4
5
6
7
8
9
10
11
12
#include<SD.h>
#include<ArduinoSound.h>
#defineI2S_DEVICE 1// this enables the I2C bus
// filename of wave file to play
// file name must be 8 chars (max) .3 chars
constcharfilename[] ="MUSIC.WAV";
// variable representing the Wave File
SDWaveFile waveFile;
// timestamp for printing the current time:
longlastPrintTime =0;
Initialize the SD card
In the setup, you need to check that the components are working. If any of them fail, it’s a good idea to stop and notify the user. Since there’s no user interface in this basic sketch, you’ll use the Serial Monitor.
First, check that the SD card works:
1
2
3
4
5
6
7
8
9
10
11
12
13
voidsetup() {
// Open serial communications:
Serial.begin(9600);
// wait for serial monitor to open:
while(!Serial);
// setup the SD card.
Serial.print("Initializing SD card...");
if(!SD.begin()) {
Serial.println("SD card initialization failed!");
while(true); // do nothing
}
Serial.println("SD card is valid.");
Open the .wav File
Once you know the SD card is good, open the file as a .wav file and check that it can play:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// create a SDWaveFile
waveFile =SDWaveFile(filename);
// check if the WaveFile is valid
if(!waveFile) {
Serial.print("There is no .wav file called ");
Serial.println(filename);
while(true); // do nothing
}
// print the file's duration:
longduration =waveFile.duration();
Serial.print("Duration = ");
Serial.print(duration);
Serial.println(" seconds");
// check if the I2S output can play the wave file
if(!AudioOutI2S.canPlay(waveFile)) {
Serial.println("unable to play wave file using I2S");
while(true); // do nothing
}
Set the Volume
Once you know the file’s good to play, set the volume and start playing. The AudioOutI2S.volume() function takes levels from 0-100. This will end the setup() function:
1
2
3
4
5
// set the playback volume:
AudioOutI2S.volume(80);
// start playback
Serial.println("playing file");
AudioOutI2S.play(waveFile);
What To Do While While Playing
While the file is playing, you don’t need to do anything. It will play regardless of what you are doing in the loop() function. However, you can check to see if it is playing or paused, and you can check the current time. These can be useful for user interface actions like responding to a play/pause button, changing the volume, and so forth.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
voidloop() {
if(millis() -lastPrintTime > 1000) {
Serial.print(waveFile.currentTime());
Serial.println( " seconds");
lastPrintTime =millis();
}
if(!AudioOutI2S.isPlaying()) {
Serial.println("File has stopped");
while(true); // do nothing
}
if(AudioOutI2S.isPaused()) {
Serial.println("File is paused");
}
}
With that much code, you’ve got enough to play a file. You can find the complete sketch at this link. Upload this sketch to your Nano and connect a headphone or speaker via a cable to the 3.5mm audio jack. Once you open the Serial Monitor, the setup messages will print to let you know things are working, and then current time in seconds will print until the song is done. Then the sketch will stop and do nothing.
The AudioSound library gives you a lot of capability to build .wav file playback devices. Try building a simple audio player with play/pause/rewind buttons. Add a button to skip to the next track. Or try building a sample player that lets you play short files like instrument notes.
In this lab, you’ll see synchronous serial communication in action using the Inter-integrated Circuit (I2C) protocol with a time-of-flight distance sensor and a microcontroller.
Many different sensors on the market use the I2C protocol to communicate with microcontrollers. It is the most common way to connect to advanced sensors these days. The VL53L0X used in this lab is typical of an I2C sensor, so the principles covered here will help you when working with other I2C sensors as well. Much of this lab is adapted from the I2C lab on the APDS-9960 Color, Light, and Gesture Sensor.
Figure 1-3 are the parts that you need for this lab.
Figure 1. 22AWG solid core hookup wires.
Figure 2. Arduino Nano 33 IoT or other Arduino board
Figure 3. A VL53L0X distance sensor breakout board.
Sensor Characteristics
The sensor used in this lab, an ST Micro VL53L0X sensor, is an integrated circuit (IC) that can read the distance out to about 2000mm. It uses a 940 nm VCSEL emitter (Vertical Cavity Surface-Emitting Laser) that reflects off the target to determine the distance. There are breakout boards available for this sensor from multiple vendors, including Adafruit and Pololu (all available through Digikey, among others) .
I2C Connections
Connect the sensor’s voltage and ground pins to your voltage and ground buses, and the I2C clock (SCL) and I2C serial data (SDA) pins to your microcontroller’s corresponding I2C pins as shown in Figure 4-6. The schematic, Figure 4, is the same for both the Uno and the Nano. For the Arduino Uno or the Arduino Nano boards, the I2C pins are pins A4 (SDA) and A5(SCL). This is the same connection for almost any I2C sensor.
Some I2C sensors also have a few other pins:
an interrupt pin, used to signal the microprocessor when a reading is ready.
a shutdown or reset pin, used for powering down or resetting the sensor.
For this exercise, you won’t be using interrupt or shutdown pins.
What are Qwiic/Stemma/Grove/Gravity?
In addition to the standard I2C connections, Sparkfun and Adafruit use a connector called Qwiic which connects the I2C, power, and interrupt connectors all in one cable, eliminating the need for soldering. It’s a Sparkfun brand name. However, you’ll need a Qwiic adapter shield to use it. Adafruit have a similar brand called Stemma, Seedstudio uses Grove, and DFRobot uses Gravity. They all support I2C and have custom solderless connectors, though their connectors are not compatible with each other. To maintain compatibility, stick with the I2C header pins.
Figure 4. Schematic view of an Arduino attached to an VL53L0X sensor. This is the typical schematic for most I2C sensors.
Figure 5. Breadboard view of an Arduino attached to a VL53L0X sensor. This shows an Adafruit breakout board, but other companies’ boards use the same pins: voltage, ground, SDA, and SCL.
Figure 6. A VL53L0X distance sensor breakout board connected to an Arduino Nano 33 IoT. This shows an Adafruit breakout board, but other companies’ boards use the same pins: voltage, ground, SDA, and SCL.
The circuit is now complete, and you’re ready to write a program to control it. One of the advantages of the I2C synchronous serial protocol (as opposed to the SPI protocol) is that you only ever need two wires for communication to one or multiple devices.
How I2C Sensors Work
I2C devices exchange bits of data whenever the shared clock signal changes. Controller and peripheral devices both send bits of data when the clock changes from low to high (called the rising edge of the clock). Unlike with SPI, they cannot send data at the same time.
The Vl53L0X has a series of memory registers that control its function. You can write to or read from these registers using I2C communication from your microcontroller. Some of these registers are writable by the controller so that you can configure the sensor. Some registers are configuration registers. Writing to them sets the sensor’s characteristics. For example, you can configure whether the sensor is in high speed mode, high sensitivity mode, or long distance mode. Other memory registers are read-only. For example, when the sensor has read the proximity of an object, it will store the result in a register that you can read from the controller. The details of the chip’s registers can be found in thesensor’s datasheet.
How I2C Bits are Exchanged
Most of the time, you never have to think about how the bits of an I2C message are exchanged. If so, then you might want to skip to the the next section on I2C Libraries. For the low-level details, read on:
I2C devices exchange data in 7-bit chunks, using an eighth bit to signal if you’re reading or writing by the controller or for acknowledgement of data received. The top seven bits of a byte are the data bits, and the bottom bit is the read/write bit. To get the distance from the VL53L0X, your controller device sends the sensor’s address (a 7-bit number, for this sensor it’s 0×29) followed by a single bit indicating whether you want to read data or write data (1 for read, 0 for write). That means the address byte is 0x53 for read, 0x52 for write access. Then you send the memory register in which the sensor’s ranging data is stored. The sensor then sends the value of that register back to you. For this particular sensor, STMicro wraps the control register documentation in an abstracted API, described in this document. The section labeled “Define Registers” lists all the registers and their addresses. The RESULT_RANGE_STATUS register is the register that holds the latest distance reading.
I2C and the Wire Library
The Wire library, which is built into the Arduino IDE, is the main library for accessing I2C communication. However, most Arduino-compatible I2C device libraries incorporate this library, but don’t expose it directly in their APIs. This makes things simpler for the user. Instead of having to work out the details described above, for example, you can just call a function like readRangeResult() which does the I2C work for you.
The libraries for this sensor are typical of this style of library. For example, the Adafruit_VL53L0X library’s startRange() command sends a write command to start a reading of the sensor. The isRangeComplete() sends a read command to read the register that indicates whether or not the reading is done.
All sensors take a certain amount of time to read the physical phenomena which they sense. With light-based sensors like the VL53L0X, the time they take to get a reading is usually called ranging time, or ranging measurement time, and it’s noted in the data sheet how long it is (about 23ms). In operation, you query the sensor as to whether it’s got a reading available, and then read it when that’s true.
How To Pick a Library
Most companies that make breakout boards for a given I2C sensor will also write a library for it. A search on the term “VL53L0X” in the Arduino library manager will return several libraries. All of them will work with any of the breakout boards. What’s the difference? Ideally, you want a library that works well, has readable examples, and good documentation. Often you have to settle for two of the three.
Different companies and programmers have different styles for writing a library’s application programming interface, or API. Arduino has a style guide for writing APIs, but it’s not always followed by others. The Arduino-developed libraries generally follow this guide. Other companies’ libraries may have a few more configuration functions, and their examples are a bit more complicated as a result. You should look at the examples with any library to see if they make sense to you. A good guideline is to use the library with the instructions and examples that you find to be the clearest. Here is the Adafruit guide for this sensor. As you can see, it doesn’t tell you much about the functions themselves. However, you can also get information from the library’s header file. The header file is generally the file with the name libraryname.h. Sometimes it’s in a directory called src. For example, here’s the header file for the Adafruit_VL53L0X library. Within the header file, there are class names for the library and a section called public where you’ll find all the possible function definitions.
Even if the examples don’t include all the functions, the public section of the header file will. From there, you can build your own examples if the library’s examples don’t show how to use a function you want to use.
Adafruit’s library for this sensor is quite complex, and includes two different ways of reading the sensor. In their examples, they use a function called rangingTest(), which puts data into an object in memory called measure in the examples, and then you pull the readings from that object. However, you can also read the results directly using a set of simpler functions:
startRange() – starts the sensor taking a single reading
readRange() – returns a single range reading
readRangeResult() – returns a single range reading, and an error value (oxFFFF) if there’s an error
startRangeContinuous() – starts the sensor reading continuously
isRangeComplete() – returns true when a reading is complete and ready to be read
waitRangeComplete() – does nothing until the reading is complete
Pololu’s library is similar, but the API is a bit simpler, and their header file lists all the register addresses, for those interested in the lower-level details. They document all the functions on their repository’s main page as well. Their product documentation is clear, if shorter than Adafruit’s.
Install the External Libraries
You can use the library manager to find these libraries. Make sure you’re using Arduino version 1.8.14 or later. From the Sketch menu, choose Include Library, then Manage Libraries, and search for VL53L0X. All of the related libraries mentioned here will show up. The examples below use the Adafruit_Vl53L0X library.
Program the Microcontroller
At the beginning of your code, include the appropriate libraries. In the setup(), initialize the sensor with a function called begin() (Sparkfun sometimes uses init() instead of begin()). If the sensor responds, then begin() will return true; if not, it will return false. This is how to check that the sensor is properly wired to your microcontroller, and to configure it:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// include library
#include"Adafruit_VL53L0X.h"
// make an instance of the library:
Adafruit_VL53L0X sensor =Adafruit_VL53L0X();
constintmaxDistance =2000;
voidsetup() {
// initialize serial, wait 3 seconds for
// Serial Monitor to open:
Serial.begin(9600);
if(!Serial) delay(3000);
// initialize sensor, stop if it fails:
if(!sensor.begin()) {
Serial.println("Sensor not responding. Check wiring.");
while(true);
}
/* config can be:
VL53L0X_SENSE_DEFAULT: about 500mm range
VL53L0X_SENSE_LONG_RANGE: about 2000mm range
VL53L0X_SENSE_HIGH_SPEED: about 500mm range
VL53L0X_SENSE_HIGH_ACCURACY: about 400mm range, 1mm accuracy
In the main loop() function, you’ll read the sensors. You’re going to query the sensor to see if it’s got a reading available with the isRangeComplete() function, then you’ll use the readRangeResult() function to get the result. This function returns a result in millimeters:
1
2
3
4
5
6
7
8
9
10
11
12
13
voidloop() {
// if the reading is done:
if(sensor.isRangeComplete()) {
// read the result:
intresult =sensor.readRangeResult();
// if it's with the max distance:
if(result < maxDistance) {
// print the result (distance in mm):
Serial.println(result);
}
}
}
Run this sketch now, and it will print out the distance from the sensor in millimeters (link to the full sketch).
Conclusion
I2C is a common protocol among many ICs, and it’s handy because you can combine many devices on the same bus. When doing so, however, make sure the device addresses are unique. This can complicate things if you want to use multiple sensors of the same type on the same I2C bus. Fortunately, this is not often the case.
In this lab, you’ll see synchronous serial communication in action using the Inter-integrated Circuit (I2C) protocol. You’ll communicate with a color, gesture, and proximity sensor from a microcontroller.
Introduction
In this lab, you’ll see synchronous serial communication in action using the Inter-integrated Circuit (I2C) protocol. You’ll communicate with a color, gesture, and proximity sensor from a microcontroller.
There are many different sensors on the market that use the I2C protocol to communicate with microcontrollers. It is the most common way to connect to sensors these days. The one used in this lab is typical, so the I2C principles covered here will help you when working with other I2C sensors as well.
Figure 1-3 are the parts that you need for this lab.
Figure 1. 22AWG solid core hookup wires.
Figure 2. Arduino Nano 33 IoT or other Arduino board
Figure 3. An APDS-9960 color and gesture sensor breakout board.
Sensor Characteristics
The sensor used in this lab, a Broadcom APDS-9960 sensor, is an integrated circuit (IC) that can read the color of an object placed in front of it; proximity, within about 10cm; and gestures on the axes parallel to the sensor (up, down, left, and right). It senses color using four photodiodes, three of which have color filters (red, green, and blue) and one of which has no filter (clear). The color sensors are filtered to block IR and UV light. It senses gesture using four directional photodiodes, picking up reflected IR energy from a built-in IR LED. The combination of sensors is used to determine the direction of an object moving above the board, and its proximity.
The company that makes this sensor, Broadcom, doesn’t make their own breakout boards, but a few other companies do. There’s a breakout board available from Sparkfun and one from Adafruit and one from DFRobot (all available through Digikey) and there’s an APDS9960 sensor built into the Arduino Nano 33 BLE Sense board as well.
I2C Connections
Connect the sensor’s voltage and ground connections to your voltage and ground buses, and the connections for I2C clock (SCL) and I2C serial data (SDA) as shown in Figure 4-6. The schematic, Figure 4, is the same for both the Uno and the Nano. For the Arduino Uno or the Arduino Nano boards, the I2C pins are pins A4 (SDA) and A5(SCL). This is the same connection for almost any I2C sensor.
Some I2C sensors also have a few other pins:
an interrupt pin, which they use to signal the microprocessor when a reading is ready. The APDS-9960 has an interrupt pin, but you don’t have to use it if you don’t want to. Your code will need to change if you use the interrupt. You can read more about that later in this lab.
a shutdown or reset pin, which can be used for powering down or resetting the sensor. This sensor doesn’t have that pin.
What are Qwiic/Stemma/Grove/Gravity?
In addition to the standard I2C connections, Sparkfun and Adafruit use a connector called Qwiic which connects the I2C, power, and interrupt connectors all in one cable, eliminating the need for soldering. It’s a Sparkfun brand name. However, you’ll need a Qwiic adapter shield to use it. Adafruit have a similar brand called Stemma, Seedstudio uses Grove, and DFRobot uses Gravity. They all support I2C, and they all have custom solderless connectors, though they are not all compatible with each other. The most compatible way is to stick with the I2C header pins.
Figure 4. Schematic view of an Arduino attached to an APDS-9960 sensor.
Figure 5. Breadboard view of an Arduino attached to an APDS-9960 sensor. This shows a Sparkfun breakout board, but the other companies’ boards use the same pins: voltage, ground, SDA, and SCL.
Figure 6. An APDS-9960 color sensor breakout board connected to an Arduino Nano 33 IoT. This shows a Sparkfun breakout board, but the other companies’ boards use the same pins: voltage, ground, SDA, and SCL.
The circuit is now complete, and you’re ready to write a program to control it. One of the advantages of the I2C synchronous serial protocol (as opposed to the SPI protocol) is that you only ever need two wires for communication to one or multiple devices.
How I2C Sensors Work
I2C devices exchange bits of data whenever the shared clock signal changes. Controller and peripheral devices both send bits of data when the clock changes from low to high (called the rising edge of the clock). Unlike with SPI, they cannot send data at the same time.
The APDS-9960 has a series of memory registers that control its function. You can write to or read from these registers using I2C communication from your microcontroller. Some of these registers are writable by the controller so that you can configure the sensor. For example, you can set set the sensitivity of the sensor, and so forth. Some registers are configuration registers, and by writing to them, you configure the chip. For example, you can set lower and upper limits of temperature sensitivity. Other memory registers are read-only. For example, when the sensor has read the proximity of an object, it will store the result in a register that you can read from the controller. The details of the chip’s registers can be found in thesensor’s datasheet.
How I2C Bits are Exchanged
Most of the time, you never have to think about how the bits of an I2C message are exchanged, and the next section, I2C Libraries, will be more important to you. For the low-level details, read on:
I2C devices exchange data in 7-bit chunks, using an eighth bit to signal if you’re reading or writing by the controller or for acknowledgement of data received. To get the temperature from the APDS-9960, your controller device sends the sensor’s address (a 7-bit number, for this sensor it’s 0×39) followed by a single bit indicating whether you want to read data or write data (1 for read, 0 for write). This means that the 8-bit byte sent is actually 0x72 or 0x73, depending on the state of the read/write bit. Then you send the memory register that you want to read from or write to. For example, as shown in Figure 7, the proximity reading is stored in memory register 0x9C of the APDS9960. To get the proximity, you send 0x72 (0x39 shifted up one bit, with 0 in the R/W bit); then 0x9C for the register you want to read. The response in this case is 0x77. The bottom bit is a 1, meaning no ACK was sent from the sensor. That converts to a proximity reading of 118.
Figure 7. I2C data
I2C and the Wire Library
To use I2C communication on an Arduino microcontroller, you use the Wire library, which is built into the Arduino IDE. You can find Arduino-compatible libraries for many devices that use the Wire library, but never expose it directly in their APIs. The libraries for this sensor are typical of this style of library. For example, the Arduino_APDS9960 library’s readColor() command sends a write command to start a reading of the sensor’s color photodiodes. The colorAvailable() sends a read command to read the register that indicates whether or not the color reading is done.
All sensors take a certain amount of time to read the physical phenomena which they sense. With light-based sensors like the APDS-9960, the time they take to get a reading is usually called integration time, and it’s noted in the data sheet how long it is (page 4). The color sensor of the APDS-9960 has an integration time of between 2.78ms and 708ms, depending on your settings. In operation, you query the sensor as to whether it’s got a reading available, and then read it when that’s true.
How To Pick a Library
Most every company that makes a breakout board for a given I2C sensor will also write a library for it. For example, there’s the Arduino_APDS9960, the SparkFun_APDS9960, and the Adafruit_APDS9960 library. All three of these will work with any of the three breakout boards. The Arduino Nano 33 BLE sense will only work with the Arduino_APDS9960 library. Otherwise, what’s the difference?
Different companies and programmers have different styles for writing a library’s application programming interface, or API. Arduino has a style guide for writing APIs, but it’s not always followed by others. The Arduino_APDS9960 library follows this guide, and has the simplest API of the three. The Sparkfun_APDS9960 offers a few more configuration functions, as does the Adafruit_APDS9960, and their examples are a bit more complicated as a result. You should look at the examples with any library to see if they make sense to you. A good guideline is to use the library with the instructions and examples that you find to be the clearest. It’s also good to check the company’s guide to the sensor if they have one. Here are the guides for this sensor: Sparkfun Hookup guide; Adafruit guide; Arduino library reference.
You can also get information from the library’s header file. The header file is generally the file with the name libraryname.h. Sometimes it’s in a directory called src. For example, here’s the header file for the Arduino_APDS9960 library. Here’s the one for the Sparkfun library and the one for the Adafruit library. Within the header file, there’s a class names for the library and a section called public where all the possible function definitions are.
Even if the examples don’t include all the functions, the public section of the header file will. From there, you can build your own examples if the library’s examples don’t show how to use a function you want to use.
All three libraries operate in more or less the same way, because they have to access the same functions of the sensor. They start the function (color, proximity, or gesture) using an enable function in the setup. In the main loop, they query the sensor if it’s got a reading, and then read it if it does. For example, to use the color function, the Arduino and Adafruit libraries have functions that check if the sensor’s got a good reading: colorDataReady() in the Adafruit library and colorAvailable() in the Arduino library. The Sparkfun has no function like this, so you have to add a delay between color readings.
The Sparkfun and Adafruit libraries provide functions to explicitly enable or disable the sensor’s three major functions. The Arduino library does this work implicitly by enabling each function when you call the available() functions, and disabling the function after each read. The former give you more control, but require you to make sure you’ve done the enabling and disabling. The latter is more automatic, but gives you less discrete control.
Install the External Libraries
You can use the library manager to find these libraries. Make sure you’re using Arduino version 1.8.9 or later. From the Sketch menu, choose Include Library, then Manage Libraries, and search for APDS9960. All three of the libraries mentioned here will show up. The examples below use the Arduino_APDS9960 library, as it’s the simplest of the three.
Program the Microcontroller
At the beginning of your code, include the appropriate libraries. In the setup(), initialize the sensor with a function called begin() (Sparkfun sometimes uses init() instead of begin()). If the sensor responds, then begin() will return true, and if not, it will return false. This is how to check that the sensor is properly wired to your microcontroller:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#include"Arduino_APDS9960.h"
voidsetup() {
Serial.begin(9600);
// wait for Serial Monitor to open:
while(!Serial);
// if the sensor doesn't initialize, let the user know:
if(!APDS.begin()) {
Serial.println("APDS9960 sensor not working. Check your wiring.");
// stop the sketch:
while(true);
}
Serial.println("Sensor is working");
}
In the main loop() function, you’ll read the sensors. Here’s how to read the color sensor using the Arduino_APDS9960 library. You’re going to query the sensor to see if it’s got a reading available with the available() function, then you’ll use the read() function to get the result:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
voidloop() {
// red, green, blue, clear channels:
intr, g, b, c;
// if the sensor has a reading:
if(APDS.colorAvailable()) {
// read the color
APDS.readColor(r, g, b, c);
// print the values
Serial.print(r);
Serial.print(",");
Serial.print(g);
Serial.print(",");
Serial.print(b);
Serial.print(",");
Serial.println(c);
}
}
You can run this sketch now, and it will print out values for red, green, blue, and clear channels, like so (Here’s a link to the full sketch):
Sensor is working
17,12,16,40
17,12,16,41
17,12,16,41
17,12,16,41
17,12,16,41
17,12,16,40
16,12,16,40
16,11,15,39
As you can see, you’re never actually calling commands from the Wire library directly, but the commands in the sensor’s library are relying on the Wire library. This is a common way to use the Wire library to handle I2C communication. If you’re looking for more examples with this sensor, the libraries all come with examples when you install them. There are some other examples for this sensor in the github repository for this class, using all three libraries. There are two important things to note:
None of the three libraries give light readings in lux, or proximity readings in millimeters.
All of the libraries are controlling the same sensor, and therefore can yield the same results. You may need to configure the sensor differently for each library though. Check the header files for each library (Arduino, Adafruit, Sparkfun) to learn their configuration functions, and check the data sheet to learn more about the sensor’s characteristics.
Using the Sensor’s Interrupt
Most I2C sensors include an interrupt pin. This pin can be used to signal the microcontroller when something important happens, like when the sensor has a good reading, or when the sensor reading crosses a particular threshold. Using the interrupt means that as soon as the sensor is ready to give you a reading, it interrupts the microcontoller.
The interrupt pin for an I2C sensor is usually configurable through the sensor’s API. For example, with the Sparkfun and Adafruit libraries for this sensor you can set the interrupt to signal when any of the three functions changes significantly, and with the Sparkfun library you can set the low and high thresholds for the proximity function.
For basic use of most sensors, you don’t need the interrupt, for for advanced use, it can be helpful. For more on using interrupts, see the Arduino reference page on interrupts.
Conclusion
I2C is a common protocol among many ICs, and it’s handy because you can combine many devices on the same bus. You need to make sure the device addresses are unique. Some devices will have fixed addresses, so that you can’t use multiples of the same sensor together. Others will have a way to change the address. For the APDS9960, the address is fixed.
In this lab you’ll learn about sensor data logging and use SPI communication to write data to a microSD card from an Arduino.
In this lab you’ll learn about sensor data logging and use SPI communication to write data to a microSD card from an Arduino.
Introduction
Sometimes you need to collect data with a microcontroller when there’s no way to communicate with another computer while you’re doing it. This is where removable storage like an SD card helps. In this lab, you’ll see how to use the Serial Peripheral Interface (SPI) protocol to write to an SD card. You’ll take sensor readings on a microcontroller and write them to a file on the SD card reader using the SPI protocol. You’ll also consider what it means to collect data about physical phenomena.
If you’re interested in data visualization and analysis, you have to start by gathering data, and much of that comes from physical activity. Though this lab doesn’t address the many non-technical considerations of data gathering, Mimi Onuoha’s essay The Point of Data Collection is an excellent introduction to that topic which you should also read when considering this lab.
Though this lab introduces you to the formatting and storage of sensor data on an SD card, there are multiple factors that you must consider in order to gather sensor-based data effectively, safely, and ethically. Here are just a few:
the conditions which you want to observe,
the sensors to use, and their sensitivity, resolution, and placement
the circumstances in which you’re observing, and who will be affected by that observation and the data that results from it.
the time scale of the observation, and the frequency of your readings
the formatting of the data and and the capacity for storing it
the energy needed to read the sensors and store the data
It’s not possible to address all of those issues in this lab, but many of them will be referenced along the way.
Figure 1-5 show the components that you need for this lab.
Figure 1. 22AWG solid core hookup wires.
Figure 2. Arduino Nano 33 IoT
Figure 3. MicroSD card breakout board
Figure 4. A short solderless breadboard.
Figure 5. A sensor.
Connect a Sensor to a Microcontroller
The sensors you use will depend on the activity you’re planning to study. For this exercise, start with a sensor that you’ve already learned how to use. Connect connect the sensor to your microcontroller. It might be a digital or analog input. It might be OneWire, like the DHT11 or DHT22 temp/humidity sensors. It might be I2C, like the APDS-9960 light sensor shown in Figure 5 (and covered in this I2C lab), or the TMP007 temperature sensor (covered in this lab). It could be built into your microcontroller board, like the IMU sensor built into the Nano 33 IoT (and covered in this lab). It might be asynchronous serial, like a GPS receiver. Getting the sensor’s data into the microcontroller is up to you.
Verify that the sensor’s working with the microcontroller by getting an initial reading.
The code below uses a generic analog input as sensor, to simplify the code. Once you have this working, you should add the appropriate code to read your particular sensor.
Connect an SD Card Reader to the Microcontroller
SD cards use the Serial Peripheral Interface (SPI) protocol to communicate with microcontrollers and other computers. SPI is a synchronous serial protocol that supports two-way communication between a controller device such as a microcontroller and a peripheral device like an SD card reader. All SPI devices have a common set of connections:
a Serial Data In (SDI) connection, on which the controller sends data to the peripheral devices.
a Serial Data Out (SDO) connection, on which the peripheral devices send data to the controller.
a SerialClock (SCLK) connection, on which the controller sends a regular clock signal to the peripheral devices.
one or more Chip Select (CS) connections, which the controller uses to signal the peripheral devices when to listen to incoming data and when to ignore it.
The SPI pin numbers are the same numbers for the Uno and Nano 33 IoT, as follows:
SDO – pin 11
SDI – pin 12
SCK – pin 13
CS – pin 10
If you’re using a MKRZero, it has a built-in SD card and a built-in SD card chip select called SDCARD_SS_PIN.
The MicroSD card reader/writer shown in Figures 3, 7, and 8 is from Sparkfun, and has level-shifting circuitry built-in to adjust for either 3.3- or 5-volt operation. There are many other models on the market though. Here’s an Adafruit model. Here’s a Pololu model. Here’s a DFRobot model. All of them will communicate with your microcontroller in basically the same way, though, using the SPI pin connections.
Most SD card readers have a card detect (CD) pin as well, that changes state when the card is inserted or removed. It’s optional, but it can be useful to make sure you have a card in the reader.
Connect your Arduino to the SD card reader as shown in Figure 6 and 7. If you’re using the Sparkfun SD card reader/writer, the pins are on the on the left side of the board, and they’re numbered, from top to bottom, as follows:
Vcc – voltage in. Connects to microcontroller voltage out
CS – Chip select. Connects to microcontroller CS
DI – SPI data in. Connects to microcontroller SDO
SCK – SPI clock.. Connects to microcontroller SCLK
DO – SPI data out.. Connects to microcontroller SDI
CD – card detect. Connects to microcontroller pin 9
GND – ground. Connects to microcontroller ground
Figure 6. Breadboard view of a microSD card breakout board attached to a Nano 33 IoT.
Figure 7. Schematic drawing of a microSD card reader attached to an Arduino using SPI connections
Format the SD Card
Different operating systems use different file formats. Your SD card needs to be formatted as FAT16 or FAT32 in order to work with the SD card library. This format is common on Windows and Linux, but not always on MacOS computers. There are some notes on formatting on the Arduino SD Card library reference.
Formatting an SD Card (Windows)
On Windows, right-click the disk and choose “Format…” The fedault formatting option is FAT32, which will work for this lab.
Formatting an SD Card (MacOS)
You can format a card as FAT32 using the MacOS Disk Utility application by selecting the SD card, Clicking the Erase button or typing command-shift-E, then selecting MS-DOS (FAT) from the Format Option menu that appears in the Format dialog. Figure 8 shows a screenshot of the MacOS Disk Utility application.
Figure 8. A screenshot of the MacOS Disk Utility Application showiing the Erase Disk Format option
Import the SD Library
With most SPI devices, you generally won’t write your own SPI commands. Most every company that makes a breakout board for a given SPI device will also write a library for it. The device-specific library abstracts away the process of using the SPI commands for the device.
Since SD card formats are a known standard, the SD card library for Arduino works with multiple different card readers, and was contributed to by authors from multiple companies. The library comes with several useful example programs to test your card reader and your card. Once you’ve installed the library from the Library Manager, you can find these examples if you click the File menu, examples submenu, then the SD submenu.
Test the SD card Reading and Writing
The CardInfo sketch will read the SD card and print out its formatting info and a list of files. This is a good place to start, to see if you formatted the card correctly. The Files example will read the card and check for a file called example.txt on the card. ListFiles will print a list of the card’s file directory. With any of these, make sure to change the chipSelect pin number to the same pin as your board. If all of those work, you’re ready to write your sketch. There’s one in the library examples, but the code below walks you through the steps of writing your own.
A Datalogger Sketch
The first thing you need to do in your sketch is to include the SD card library at the top. The library includes a File class, which you can read to and write from like a file. Make an instance of that class, and make a constant for the file name. Make the file type .csv (comma-separated values) so the file is easy to read with a spreadsheet application later. Add constants for the chip select and card detect pins as well, and a variable to keep track of when your last successful reading was logged to the card:
1
2
3
4
5
6
7
// the SPI CS pin
constintchipSelect =10;
constintcardDetect =9;
// the filename. Use CSV so the result can be opened in a spreadsheet
constcharfileName[] ="datalog.csv";
// time of last reading, in ms:
longlastReading =0;
The File class implements many of the same functions as the Serial class that you’re already familiar with, like read(), write(), print(), println(), and available(). Both File and Serial are instances of a data class called a Stream. You’ll see other examples of Stream in other libraries for communication, like I2C and WiFi.
This sketch won’t use the Serial Monitor, since you won’t be attached to a computer when you’re reading data. Instead, you’ll use the built-in LED to tell whether things are working or not.
Detect and Initialize the Card
In the setup(), initialize the LED, and use the card detect pin to tell if there’s a card present or not. When it’s there, use the SD.begin() to attempt to initialize the card. The SD.begin() function’s parameter is the chip select pin number.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
voidsetup() {
// variable for the LED's state:
intledState =HIGH;
pinMode(LED_BUILTIN, OUTPUT);
pinMode(cardDetect, INPUT);
// if the card detect pin is false, no card:
while(digitalRead(cardDetect) ==LOW) {
// toggle LED every 1/4 second while the SD card's not present:
digitalWrite(LED_BUILTIN, HIGH);
}
// give the reader 5 seconds to settle the card once it's detected:
delay(5000);
// if the card is not present or cannot be initialized:
while(!SD.begin(chipSelect)) {
// toggle LED every 1/4 second while the SD card's not responding:
digitalWrite(LED_BUILTIN, ledState);
// change the LED state:
ledState =!ledState;
delay(250);
}
// turn the LED off:
digitalWrite(LED_BUILTIN, LOW);
}
Set the Reading Interval
Start the main loop() function by checking the millis() function to see if one second (1000 ms) have passed since your last successful reading. Later in the code, you’ll update the lastReading variable using the millis() function:
1
2
3
voidloop() {
// read once a second:
if(millis() -lastReading > 1000) {
Read the Sensors and Format for Writing
Next, set up a String variable, and use it to collect your sensor readings and any formatting, like the commas that will separate the readings. Then read your sensors and add them to the String:
1
2
3
4
5
6
7
8
9
10
11
// make a string for assembling the data to log:
String dataString ="";
// read your sensors:
intsensorOne =analogRead(A0);
dataString +=String(sensorOne);
delay(1);
// comma-separate the values:
dataString +=String(",");
intsensorTwo =analogRead(A1);
dataString +=String(sensorTwo);
Write to the File
Once you’ve got the data formatted, check to see if you can open the File you created on the SD card for writing. If you can, then write to it. Turn the LED on when you’re writing, and off when you’re not, so you know when the card is busy. When you turn the LED off, update the lastReading variable with the time fron millis(). If you can’t access the file, turn the LED on constantly to indicate that there’s a problem. After that, you can close the initial if() statement that checks the time, and close the main loop:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// open the file. Only one file can be open at a time,
// so you have to close this one before opening another.
File dataFile =SD.open(fileName, FILE_WRITE);
// if the file is available, write to it:
// turn the LED on while writing and off when not writing too:
if(dataFile) {
digitalWrite(LED_BUILTIN, HIGH);
dataFile.println(dataString);
dataFile.close();
digitalWrite(LED_BUILTIN, LOW);
lastReading =millis();
} else{
// if the file can't be opened, leave the LED on:
digitalWrite(LED_BUILTIN, HIGH);
}
} // end of if millis() statement
} // end of loop
the dataFile.close() function is the one that actually stores the data to the card, so when that’s done, you know the data should be on the SD card. If you don’t want to open and close a lot, you can also use the dataFile.flush() function to write to the card.
That’s the whole working sketch. Try it. Once it’s run for a minute or so, remove the SD card, put it in your computer and see if there’s a file called datalog.csv on it. Open the card in a spreadsheet program to see your data.
Even though your sensor might be able to deliver multiple readings a second, you have to decide how frequently you need to record the results. For example, if you’re measuring temperature change in a room, do you need to read more frequently than once a minute?
How you format the data for storage and how frequently you read it affects how much memory it takes. For example, imagine you’re reading a temperature sensor and storing the results as a string, like so:
21.45°C
Each character of that reading takes a byte of data. So each reading would take about 6 to 8 bytes, depending on how many digits are involved, and whether you use a label like “°C” or not. If you’re reading from multiple sensors, or adding a time stamp to each reading, each reading can easily take 10 to 20 bytes or more.
Now, imagine you plan to store readings ten times a second. For every second, that’s 100 bytes. For every minute, 6 kilobytes. For every hour, 360 kilobytes. For every day, 8.6 megabytes.
Each reading takes energy as well. Different sensors draw differing amounts of current, as does an SD card reader. To find out how much, you could program your microcontroller to write once a second, and then measure the current over several seconds to see the differences in current draw when it’s measuring and when it’s not.
Given all of that, how frequently should you read your sensors? It depends on the activity. If you’re trying to record a hand or arm gesture using an an IMU sensor, you should read multiple times a second, because even a tenth of a second can change where the limb you’re measuring is. If you’re recording the change in air quality in your home, the air probably doesn’t move that fast, so once a minute, or even less, might be fine. Before you can build the circuit or write any code, you should make these decisions, to simplify the development of your device.
Time Stamp the Data
In order to see how the data changes over time, you need to keep track of when each reading was recorded. For many short-term datalogging experiments, you can simply use the millis(), or divide the millis() by 1000 to get seconds. That method loses a few seconds every day, but it’s fine if you’re logging data only for a few minutes or an hour or so. If you’re recording for longer or you need precise time of day and you are using a MKR board or the Nano 33 IoT, you can use the real-time clock that’s built into it, using the RTCZero library. A real-time clock (RTC) is an electronic component that keeps accurate time, usually attached to a microcontroller via synchronous serial communications protocols like I2C or SPI. The SAMD21 processor that’s at the heart of the MKR boards and the Nano 33 IoT has a built-in RTC. Here’s a lab that explains how to do that.
Conduct the Measurements
Once you’ve gotten your code and circuit working, it’s time to take some readings. Place the sensor where it can read the activity you want to read, and let it run for a short interval. If it’s not supposed to be sensing your activity, leave it alone while it’s doing its job. Then turn it off, remove the SD card, and read the data on your personal computer. Once you’re confident that your device is working as you intended it, you can set it up to run for a longer time.
Review the Data
Since you saved the file as a .csv file, it will most likely open up in your favorite spreadsheet application, and you can see the results in a table. This can be very handy for looking through the data in a systematic way. You can then sort it by highest value, or by time (it should already be sorted by time), or if you are using multiple sensors, you can sort by one sensor value or the other.
Visualize the Data
The other advantage of using a spreadsheet program is that most all of them have a graphing tool built in that will allow you to graph the results of your sensor readings, as shown in Figure 9. With a graph, you can look for patterns in the changes of data visually. Of course, you could write your own graphing program in p5.js or Processing or some other program, but by using a standard data format (CSV), and writing to a file on an SD card, you’ve made it possible to use existing software tools to analyze the data from your sensors.
Figure 9. A screenshot of LibreOffice spreadsheet showing the sensor readings and a graph of the readings from the sketch above.
Powering the Datalogger for Long-Term Measurements
If you’re setting up an environmental sensor, or a sensor to read the changes in a space over a long time, you’ll need a way to power your device. If there’s electrical power, you could simply plug the device into the wall using a USB adapter. If you can’t plug into the wall, you’ll need a battery. For some background on voltage and power, view this video on electrical power.
Battery Capacity
Batteries are rated by voltage and energy capacity. Capacity isusually given in milliamp-hours. You might think that if a battery is a 2000mAh (2000 milliamp-hours), the battery can supply a maximum of 2000 milliamps at a given instant when it’s charged, and can do so for up to one hour. That’s not the whole story though. Batteries don’t charge or discharge in a linear fashion, though. Maximum charging and discharging rates are relative to a battery’s total capacity; in other words, larger batteries can both supply higher currents, and charge at higher currents.
Batteries are tested at a “C-rate”, which you can find in their data sheet, that actually determines the maximum current that a batterycan supply. A 1000 mAh battery could provide more than 1 amp depending on it’s maximum discharge C-rating. If the rate is 2C, then the battery could provide 2 amps (for less than the full hour, of course). For example, here’s a 2000 mAh battery from Adafruit. This battery’s data sheet indicates that its performance was rated at 0.2C, indicating that though it’s rated for 2000 mAh, its standard charging and discharge current is 0.5 amps.
Mobile phone charging battery packs can be convenient because they already have a USB plug on them. It’s easy to find packs that have a capacity of 1000 mAh or more at 5 volts. A variety of standard battery combinations can work, like a 9V battery or a set of AA cells in a battery clip. AA batteries are typically 1.5V each, so you’d need a 3- or 4-battery clip to get enough voltage to run your processor.
Rechargeable 3.7V lithium polymer batteries are available too (also called Lithium-ion, Li-Ion, LiPoly, or LiPo), and can run the Nano 33 boards, though usually not an Uno. These are useful because you can reuse them many times, unlike other batteries. These are often found inside the mobile phone chargers mentioned earlier (and in mobile devices and laptops). Here are some examples:
Make sure to check the connector type on your Li-ion batteries. The most common connector is a 2-pin JST-PH connector, but some manufacturers use variations on this. Also check the polarity, as sometimes they come wired backwards. Connecting a battery to a charger backwards can damage both.
With these, you’ll need a charger. There’s one built into the MKR boards, and there are number of charger options. Here are a few:
Only charge lithium batteries with a dedicated charger designed for the specific type and number of cells you are using! The Adafruit chargers, for example, can only charge 1-cell batteries with 3.7V/4.2V cells. A rechargeable battery must be charged at a specific safe charging rate,. All batteries are potentially explosive if mis-handled or misused in charging and discharging, and lithium batteries can be particularly volatile, as this animation of a man biting a battery like an old-timey prospector biting a gold coin shows.
Put Your Microcontroller to Sleep When it’s not Reading
Your device consumes power when even when it’s not running, and when you’re running on battery power, that means you can log less data before the battery dies. One way to get more readings out of a battery is to put the microcontroller to sleep. Different microcontrollers have different modes of sleep that they can use. The Uno, unfortunately, has no easy sleep mode, but the Nano 33 IoT and MKR boards do, using the ArduinoLowPower library. With this library, you can put the microcontroller into a number of low power modes, and wake it up, either after a set time using the real time clock, or from a change on input pin (called an external interrupt):
Idle – this mode has the fastest wake-up time, but the least power savings. The processor is stopped, but peripherals like the realtime clock (RTC), analog-to-digital converter (ADC) and Serial, and I2C are not.
Sleep – this mode allows has slower wakeup time, but better power savings. Only the peripherals you’re using in your sketch remain on.
Deep sleep – This mode has the the slowest wake-up time and the best power savings. All but the realtime clock peripherals are stopped. The CPU can be woken up only using the clock or interrupt pins.
Conclusion
Though this lab is primarily about connecting an SD card reader to a microcontroller to write sensor-based data to an SD card, this exercise has lots of secondary factors which you need to consider, from the energy needed to gather the data to the design of the data-gathering experiment to the individuals whose activities are represented in the data. All of these come into play even before you consider how to present the data that you’ve gathered. Hopefully this introduction has given you a starting place from which to consider those factors.
Note: Many I2C sensors from providers like SparkFun (Qwiic) and Adafruit (STEMMA QT) come in two variants:
