Secure DIY garage door opener a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1113

Introduction

If you'd like to increase the security of your garage door, or you are just interested in learning more about cryptography, then read on! At its core, this project is simply about a secure wireless button. This could be used to trigger any number of things, so we hope it can inspire message security on many other future projects.

I was surprized to learn that even if your garage door is fairly new, then you may still be vulnerable to man-in-the-middle or roll-jam attacks. With this tutorial, you can achieve an extremely high level of security utilizing ECC signatures and the SparkFun Cryptographic Co-processor.

If you'd like to read more about garage doors, here are two great articles about hacking and history.

Garage Door Hacking: What's the Deal?

A (Very) Short History of the Garage Door Opener

During my research for this project, I also came across an interesting story about garage doors in San Francisco. In 2004, military radio signals were jamming garage door openers. It seems that most garage door openers at the time were operating on the same frequency as a new military communications system (390 MHz). For more details, check out this CBS News article. After learning this, I was glad to know that my new setup is operating on 915MHz, and so shouldn't be effected.

Most communication channels are exposed to the world. Whether it's a hard wired connection or a wireless signal flying through the air, anyone can listen in and try to intercept, record and/or impersonate your signal. So how do we protect ourselves against these malicious attacks? Surprisingly, you can make a very robust solution with a couple of Pro RFs and our Cryptogrpahic Co-processors.

Suggested Reading

If you aren’t familiar with the following concepts, we recommend you read over these tutorials before continuing.

The Secure Solution

We are going to use digital signatures to add security to our system. If you want to learn more about how to use the Cryptographic Co-processor, check out this tutorial and video. These will show you the fundamental ideas behind digital signatures, walk you through how to setup each co-processor.

For the secure garage door opener example shown here, we are going to do something very similar to Example 6 in the Arduino Library. A complete cycle will follow these steps:

1. User presses button on remote to engage cycle.
2. Remote sends a "request for token".
3. Base generates a new random token (32-bytes).
4. Base sends token to remote.
5. Remote creates ECC signature on token (using its unique private key).
6. Remote sends ECC signature to base.
7. Base verifies signature using remote's public key.
8. If verified, base opens garage.

What makes this so secure is the fact that the only place in the world that can create a valid signature is inside the remote's co-processor. This is because the private key was generated randomly during configuration and will never leave the IC. If you don't have that actual piece of hardware (the remote co-processor), you will never be able to create a signature.

Also, the fact that the base creates a new random token for each cycle, allows us to prevent against man-in-the-middle and roll-jam attacks.

Wahoo! That's one heck of a secure wireless button!

Hardware Overview

For this project, we need to build up two separate circuits. One will be the remote control (that lives in my car or bike), and the second will be the base transceiver that lives inside my garage (listening for the ECC signature, and then engaging the garage door button).

Remote Control:

• Pro RF
• Duck Antennae
• Cryptographic Co-processor (for creating the ECC signature)
• Enclosure
• Button
• 400mAh Lipo Battery
• Qwiic Cable (QTY:1)

Base Transceiver:

• Pro RF
• Wire antennae
• Cryptographic Co-processor (for creating the TTL token, and verifying the ECC signature)
• SparkFun Qwiic Single Relay
• Wire antennae
• USB wall wort
• Qwiic Cable (QTY:2)

For easy one click ordering, here is a wish list. Be sure to read the entire tutorial, and then adjust as necessary.

Hardware Hookup

All of these boards use qwiic, so that made things much easier and faster to hookup.

The Remote

For the remote control, there are only 4 connections that need to be made:

The Base Transceiver

The Base Transceiver also requires hooking up just 4 connections:

Note, the order of boards in the qwiic system didn't matter, but I put the relay last so I could position it for easier access. I also soldered to the PTH pins on the bottom of the screw pin terminal, but you could choose to do a solderless connection if you like.

Integration

To engage the garage door, I opted to emulate what a human does (press the button on the wall inside). I opened up the wall-mounted controller and saw this:

Aha! I recognize those mini push button switches.Upon further inspection, I saw that there are various passive components involved:

Pretty neat how they are able to get three button control from simply two wires. I wonder if there is an ADC involved? Or maybe some sort of pulsing and time sensitive digital reads? Maybe an AC signal? What do you think?

For this project, I was only concerned with the lower momentary switch (aka the "big button"). From looking at the circuit board with backlight as shown above, I was able to see that the lower button simply connects the two leads together directly without any extra passives involved. With this in mind, I decided to use a relay and run it in parallel with the switch. I used a SparkFun Qwiic Single Relay to engage this button from my Arduino. I know this is probably overkill for the amount of current this will ever see, but I liked that this solution would be very easy to connect/control using qwiic and was a sure bet in emulating the button.

For the connection to the garage door wall-mounted button, I chose to open it up and solder to the connection points on either side of the button. After doing so, I actually realized that you could "tap" into the two wires out to the button anywhere in the line and potentially use the screw pin terminals on the relay for a solder-less connection point. Nevertheless, I used a couple XT-60 connectors on the lines, and this makes it pretty easy to take apart if necessary for re-programming.

Power Considerations

In order to save power on the remote control, I opted to put a momentary push button in series on the power input. This way, power would only be connected when I wanted to open the garage door. Otherwise, it would remain completely off. Also, with a more traditional DPST switch, we'd me more likely to accidentally leave it switched on and drain the battery. Luckily, the ProRF has a couple headers already in the design for an external switch.

Now I wanted to consider how much power is actually being used during each attempt to open the garage door. I hooked up an SparkFun RedBoard Artemis and a Zio Current and Voltage Sensor - INA219 (Qwiic), and I had some data streaming in no time!

Here is what a complete cycle looked like on the serial plotter and monitor:

Each reading is precisely 100ms apart, so adding them all up I can see that it will use 0.065mAh per cycle.

21 readings (2100ms) at 36mA = 0.021mAh

1 reading (100ms) at 56mA = 0.002mAh

20 readings (2000ms) at 76mA = 0.042mAh

Total: 0.065mAh

Battery capacity is 400mAh

400mAh / 0.065mAh = 6,153

So according to my rough math, I think I can press this button 6153 times with this single battery. At 2 times a day, 300 days a year (600/year), that's 10 years. Even with capacity loss during storage in my car (let's say 10% each year), it'll still should last... let's see...

Year: capacity : -10% - yearly use for cycles (600 * 0.065 = ~40mAh)

Year 1 : 400 - 40 - 40 = 320

Year 2 : 320 - 32 - 40 = 248

Year 3 : 248 - 25 - 40 = 183

Year 4 : 183 - 18 - 40 = 125

Year 5 : 125 - 13 - 40 = 72

Year 6 : 72 - 7 - 40 = 25

Wahoo! Six years is pretty good. Now I just need to make sure it doesn't get squashed somewhere in my car.

Arduino Code

There are two separate sketches: one for the remote control and a second for the base transceiver. You can see both sketches in the project github repository located here:

The code used in this project was kept fairly clean by using three Arduino Libraries:

• SparkFun_ATECCX08a_Arduino_Library
• SparkFun Qwiic Relay Arduino Library Github Repo
• Radiohead Arduino Library

For help with installing each necessary Arduino library, see the individual hookup guides for the Qwiic Relay and Cryptographic Co-processor. But you can also check out a more general tutorial on Arduino library installation here:

Also, to use the SparkFun Pro RF, you will need to install the SamD boards packages. You can follow along how to do that at this section of the Pro RF Hookup Guide.

Now let's take a closer look at each individual sketch.

Remote Control Sketch

This sketch basically does everything inside its setup(). This is because, it will actually remain un-powered for most of its life. When I want to power it up and begin an entire attempt cycle, I will press the momentary button on the enclosure and this will supply power.

After setting up the RF module, the cryptographic co-processor and button, the most important thing to note is that it calls "attempt_cycle" at the very end of setup(). All the good stuff happens in there!

attempt_cycle() does essentially four things:

• Engages a cycle by sending "$$$".
• Receives 64-byte token.
• Creates the ECC signature.
• Sends Signature back to the base.

    /*
  Remote Control
  This sketch is used to create a cryptographically secure wireless controller to open you garage.
  The complete system uses SparkFun Pro RF modules, Cryptographic Co-processors, and the qwiic relay.
  Note, it also requires a base transceiver setup with separate sketch.

  See the complete tutorial here:
  https://learn.sparkfun.com/tutorials/secure-diy-garage-door-opener

  By: Pete Lewis
  SparkFun Electronics
  Date: January 13th, 2020
  License: This code is public domain but you can buy me a beer if you use this and we meet someday (Beerware license).

  Feel like supporting our work? Please buy a board from SparkFun!
  https://www.sparkfun.com/products/15573

  Some of this code is a modified version of the example provided by the Radio Head
  Library which can be found here:
  www.github.com/PaulStoffregen/RadioHeadd

  Some of this code is a modified version of the example provided by the SparkFun ATECCX08a
  Arduino Library which can be found here:
  https://github.com/sparkfun/SparkFun_ATECCX08a_Arduino_Library
*/

#include <SPI.h>

//Radio Head Library:
#include <RH_RF95.h>

// We need to provide the RFM95 module's chip select and interrupt pins to the
// rf95 instance below.On the SparkFun ProRF those pins are 12 and 6 respectively.
RH_RF95 rf95(12, 6);

int LED = 13; //Status LED is on pin 13

int packetCounter = 0; //Counts the number of packets sent
long timeSinceLastPacket = 0; //Tracks the time stamp of last packet received

// The broadcast frequency is set to 921.2, but the SADM21 ProRf operates
// anywhere in the range of 902-928MHz in the Americas.
// Europe operates in the frequencies 863-870, center frequency at 868MHz.
// This works but it is unknown how well the radio configures to this frequency:
//float frequency = 864.1;
float frequency = 921.2; //Broadcast frequency


//////////////crypto stuff

#include <SparkFun_ATECCX08a_Arduino_Library.h> //Click here to get the library: http://librarymanager/All#SparkFun_ATECCX08a
#include <Wire.h>

ATECCX08A atecc;

uint8_t token[32]; // time to live token, created randomly each authentication event


/////////////

byte buf[RH_RF95_MAX_MESSAGE_LEN];

void setup()
{
  pinMode(LED, OUTPUT);

  SerialUSB.begin(115200);
  // It may be difficult to read serial messages on startup. The following line
  // will wait for serial to be ready before continuing. Comment out if not needed.
  //while (!SerialUSB);
  SerialUSB.println("RFM Client!");

  //Initialize the Radio.
  if (rf95.init() == false) {
    SerialUSB.println("Radio Init Failed - Freezing");
    while (1);
  }
  else {
    //An LED inidicator to let us know radio initialization has completed.
    //SerialUSB.println("Transmitter up!");
    //digitalWrite(LED, HIGH);
    //delay(500);
    //digitalWrite(LED, LOW);
    //delay(500);
  }

  // Set frequency
  rf95.setFrequency(frequency);

  // The default transmitter power is 13dBm, using PA_BOOST.
  // If you are using RFM95/96/97/98 modules which uses the PA_BOOST transmitter pin, then
  // you can set transmitter powers from 5 to 23 dBm:
  // Transmitter power can range from 14-20dbm.
  rf95.setTxPower(14, false);

  pinMode(5, INPUT_PULLUP);

  Wire.begin();

  if (atecc.begin() == true)
  {
    SerialUSB.println("Successful wakeUp(). I2C connections are good.");
  }
  else
  {
    SerialUSB.println("Device not found. Check wiring.");
    while (1); // stall out forever
  }

  attempt_cycle();

}


void loop()
{

  if (digitalRead(5) == LOW)
  {
//    attempt_cycle();
  }
  delay(10); // button debounce
}


void printBuf64()
{
  SerialUSB.println();
  SerialUSB.println("uint8_t buf[64] = {");
  for (int i = 0; i < 32 ; i++)
  {
    SerialUSB.print("0x");
    if ((buf[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(buf[i], HEX);
    if (i != 31) SerialUSB.print(", ");
    if ((31 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void printToken()
{
  SerialUSB.println();
  SerialUSB.println("uint8_t token[32] = {");
  for (int i = 0; i < sizeof(token) ; i++)
  {
    SerialUSB.print("0x");
    if ((token[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(token[i], HEX);
    if (i != 31) SerialUSB.print(", ");
    if ((31 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}


// Note, in Example4_Alice we are printing the signature we JUST created,
// and it lives inside the library as a public array called "atecc.signature"
void printSignature()
{
  SerialUSB.println("uint8_t signature[64] = {");
  for (int i = 0; i < sizeof(atecc.signature) ; i++)
  {
    SerialUSB.print("0x");
    if ((atecc.signature[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(atecc.signature[i], HEX);
    if (i != 63) SerialUSB.print(", ");
    if ((63 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void attempt_cycle()
{
  SerialUSB.println("Sending message");

  //Send a message to the other radio
  uint8_t toSend[] = "$$$";
  //sprintf(toSend, "Hi, my counter is: %d", packetCounter++);
  rf95.send(toSend, sizeof(toSend));
  rf95.waitPacketSent();

  // Now wait for a reply

  byte len = sizeof(buf);

  if (rf95.waitAvailableTimeout(2000)) {
    // Should be a reply message for us now
    if (rf95.recv(buf, &len)) {
      SerialUSB.print("Got reply: ");
      printBuf64();
      for (int i = 0 ; i < 32 ; i++) token[i] = buf[i]; // read in token from buffer.
      printToken(); // nice debug to see what token we just sent. see function below

      boolean sigStat = false;
      sigStat = atecc.createSignature(token); // by default, this uses the private key securely stored and locked in slot 0.

      SerialUSB.print("sigStat: ");
      SerialUSB.println(sigStat);

      //printSignature();


      // Copy our signature from library array to local toSend array
      //for (int i = 0 ; i < 64 ; i++) toSend[i] = atecc.signature[i]; // store locally

      //Send signature to the other radio
      rf95.send(atecc.signature, sizeof(atecc.signature));
      rf95.waitPacketSent();
      SerialUSB.println("Sent signature");
      //SerialUSB.println((char*)buf);
      //SerialUSB.print(" RSSI: ");
      //SerialUSB.print(rf95.lastRssi(), DEC);
    }
    else {
      SerialUSB.println("Receive failed");
    }
  }
  else {
    SerialUSB.println("No reply, is the receiver running?");
  }
  delay(500);
}

Base Transceiver Sketch

This sketch is very similar to the first Example Sketch in our hookup guide for the Pro RF: Point to Point Radio Arduino Examples In fact, that's were I started from. And then I added in the necessary libraries for the Cryptographic chip and the qwiic relay. And then I stole some code from each of their initial examples. A whole lot of copy/paste going on. Isn't that convenient, Gromit!

Inside the main loop, the Base does the following:

• Listens to incoming messages.
• If it receives a "$$$", then create a new random token and send it to remote.
• Listens for a signature from remote.
• Receives 64-byte signature.
• Verifies signature.
• If valid, trigger relay to "close" for 500ms, emulating a button press.
• If success hasn't happened within 1 second, destroy token. This protects against repeater attacks.

Note, whenever the Base hears any message come in, it checks for the "$$$". This will tell it if the message is an request or a signature. If it doesn't see "$$$" then it pulls in the next 64 bytes and attempts to verify the signature.

/*
  Base Transceiver
  This sketch is used to create a cryptographically secure wireless controller to open you garage.
  The complete system uses SparkFun Pro RF modules, Cryptographic Co-processors, and the qwiic relay.
  Note, it also requires a remote control setup with separate sketch.

  See the complete tutorial here:
  https://learn.sparkfun.com/tutorials/secure-diy-garage-door-opener

  By: Pete Lewis
  SparkFun Electronics
  Date: January 13th, 2020
  License: This code is public domain but you can buy me a beer if you use this and we meet someday (Beerware license).

  Feel like supporting our work? Please buy a board from SparkFun!
  https://www.sparkfun.com/products/15573

  Some of this code is a modified version of the example provided by the Radio Head
  Library which can be found here:
  www.github.com/PaulStoffregen/RadioHeadd

  Some of this code is a modified version of the example provided by the SparkFun ATECCX08a
  Arduino Library which can be found here:
  https://github.com/sparkfun/SparkFun_ATECCX08a_Arduino_Library

  Some of the code is a modified version of the example provided by the SparkFun Qwiic
  Relay Arduino Library which can be found here:
  https://github.com/sparkfun/SparkFun_Qwiic_Relay_Arduino_Library
*/



#include <SPI.h>

//Radio Head Library:
#include <RH_RF95.h>

// We need to provide the RFM95 module's chip select and interrupt pins to the
// rf95 instance below.On the SparkFun ProRF those pins are 12 and 6 respectively.
RH_RF95 rf95(12, 6);

int LED = 13; //Status LED on pin 13

int successLED = 3; // green
int failLED = 4; // red
int statLED = 2; // blue

int packetCounter = 0; //Counts the number of packets sent
long timeSinceLastPacket = 0; //Tracks the time stamp of last packet received
// The broadcast frequency is set to 921.2, but the SADM21 ProRf operates
// anywhere in the range of 902-928MHz in the Americas.
// Europe operates in the frequencies 863-870, center frequency at
// 868MHz.This works but it is unknown how well the radio configures to this frequency:
//float frequency = 864.1;
float frequency = 921.2;

uint8_t buf[RH_RF95_MAX_MESSAGE_LEN];


////////////////relay

#include "SparkFun_Qwiic_Relay.h"

#define RELAY_ADDR 0x18 // Alternate address 0x19


Qwiic_Relay relay(RELAY_ADDR);

////////////////

/////////////////crypto

#include <SparkFun_ATECCX08a_Arduino_Library.h> //Click here to get the library: http://librarymanager/All#SparkFun_ATECCX08a
#include <Wire.h>

ATECCX08A atecc;

uint8_t token[32]; // time to live token, created randomly each authentication event

uint8_t signature[64]; // incoming signature from Alice

int headerCount = 0; // used to count incoming "$", when we reach 3 we know it's a good fresh new message.

// Alice's public key.
// Note, this will be unique to each co-processor, so your will be different.
// copy/paste Alice's true unique public key from her terminal printout in Example6_Challenge_Alice.

uint8_t AlicesPublicKey[64] = {
  0x38, 0xD6, 0xE5, 0x49, 0xAC, 0x57, 0x2D, 0x1F, 0xD0, 0x58, 0x0A, 0xE8, 0x59, 0xB8, 0xF8, 0x20,
  0x1E, 0x0A, 0x7E, 0x8D, 0x5B, 0x7D, 0xD9, 0x8A, 0x26, 0xAF, 0x88, 0x73, 0x6D, 0x8C, 0xB7, 0x2D,
  0x8D, 0x3A, 0xB9, 0x5F, 0x60, 0x9D, 0x3F, 0x49, 0x72, 0xF1, 0x44, 0x74, 0x82, 0x3F, 0x7B, 0xCF,
  0x1F, 0x18, 0xD3, 0xA4, 0xBF, 0x62, 0x15, 0xCC, 0xAF, 0xAD, 0x7E, 0x03, 0xD8, 0xE9, 0x93, 0x7E
};

void setup()
{
  pinMode(LED, OUTPUT);
  pinMode(successLED, OUTPUT);
  pinMode(failLED, OUTPUT);
  pinMode(statLED, OUTPUT);

  SerialUSB.begin(115200);
  // It may be difficult to read serial messages on startup. The following
  // line will wait for serial to be ready before continuing. Comment out if not needed.
  //while (!SerialUSB);
  SerialUSB.println("RFM Server!");

  //Initialize the Radio.
  if (rf95.init() == false) {
    SerialUSB.println("Radio Init Failed - Freezing");
    while (1);
  }
  else {
    // An LED indicator to let us know radio initialization has completed.
    SerialUSB.println("Receiver up!");
    digitalWrite(LED, HIGH);
    delay(500);
    digitalWrite(LED, LOW);
    delay(500);
  }

  rf95.setFrequency(frequency);

  // The default transmitter power is 13dBm, using PA_BOOST.
  // If you are using RFM95/96/97/98 modules which uses the PA_BOOST transmitter pin, then
  // you can set transmitter powers from 5 to 23 dBm:
  // rf95.setTxPower(14, false);


  Wire.begin();

  if (atecc.begin() == true)
  {
    SerialUSB.println("Successful wakeUp(). I2C connections are good.");
  }
  else
  {
    SerialUSB.println("Device not found. Check wiring.");
    while (1); // stall out forever
  }

  if (!relay.begin())
  {
    Serial.println("Check connections to Qwiic Relay.");
    while (1); // stall out forever
  }
  else
  {
    Serial.println("Qwiic Relay is ready to go.");
  }

}

void loop()
{
  if (rf95.available()) {
    // Should be a message for us now

    uint8_t len = sizeof(buf);

    if (rf95.recv(buf, &len)) {
      digitalWrite(LED, HIGH); //Turn on status LED
      timeSinceLastPacket = millis(); //Timestamp this packet

      SerialUSB.print("Got message: ");
      printBuf64();
      //SerialUSB.print(" RSSI: ");
      //SerialUSB.print(rf95.lastRssi(), DEC);
      SerialUSB.println();

      // if message from Alice is "$$$", Send a random token for her to sign.
      if (buf[0] == '$' && buf[1] == '$' && buf[2] == '$')
      {
        SerialUSB.println("Received $$$. Creating a new random TTL-token now...");

        // update library instance public variable.
        atecc.updateRandom32Bytes();

        uint8_t toSend[32];
        // copy from library public variable into our local variable
        for (int i = 0 ; i < 32 ; i++)
        {
          token[i] = atecc.random32Bytes[i]; // store locally
        }

        rf95.send(token, sizeof(token));
        rf95.waitPacketSent();
        SerialUSB.println("Sent token");
        digitalWrite(LED, LOW); //Turn off status LED
      }
      else // this means Alice just sent us a signature
      {
        SerialUSB.println("Received signature. Verifying now...");
        for (int i = 0 ; i < 64 ; i++) signature[i] = buf[i]; // read in signature from buffer.
        printSignature();
        // Let's verirfy!
        if (atecc.verifySignature(token, signature, AlicesPublicKey))
        {
          SerialUSB.println("Success! Signature Verified.");
          // Let's turn on the relay...
          relay.turnRelayOn();
          delay(1000);
          // Let's turn that relay off...
          relay.turnRelayOff();
          blinkStatus(successLED);
        }
        else
        {
          SerialUSB.println("Verification failure.");
          blinkStatus(failLED);
        }
      }

    }
    else
      SerialUSB.println("Recieve failed");
  }
  //Turn off status LED if we haven't received a packet after 1s
  if (millis() - timeSinceLastPacket > 1000) {
    digitalWrite(LED, LOW); //Turn off status LED
    timeSinceLastPacket = millis(); //Don't write LED but every 1s
    clearBuf();
    // destory token, to require a new cycle if this doesn't complete within 1 second
    for (int i = 0 ; i < 32 ; i++)
    {
      token[i] = 0x00;
    }
  }
}


void printSignature()
{
  SerialUSB.println("uint8_t signature[64] = {");
  for (int i = 0; i < sizeof(signature) ; i++)
  {
    SerialUSB.print("0x");
    if ((signature[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(signature[i], HEX);
    if (i != 63) SerialUSB.print(", ");
    if ((63 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void printBuf64()
{
  SerialUSB.println();
  SerialUSB.println("uint8_t buf[64] = {");
  for (int i = 0; i < 64 ; i++)
  {
    SerialUSB.print("0x");
    if ((buf[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(buf[i], HEX);
    if (i != 63) SerialUSB.print(", ");
    if ((63 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void clearBuf()
{
  for (int i = 0; i < 64 ; i++) buf[i] = 0x00;
}

void blinkStatus(int LED)
{
  digitalWrite(LED, HIGH);
  delay(2000);
  digitalWrite(LED, LOW);
  delay(500);
}

Resources & Going Further

Now that you've incorporated ECC authentication security into your garage door opener, you can add security to any future project they may need it. How about your internet-connected front door?

For more information, check out the resources below:

Project Source Code:

• Project GitHub Repository

Hookup Guides:

• SAMD21 Pro RF Hookup Guide
• Cryptographic Co-Processor ATECC508A (Qwiic) Hookup Guide
• Qwiic Single Relay Hookup Guide

Arduino Libraries:

• SparkFun_ATECCX08a_Arduino_Library
• SparkFun Qwiic Relay Arduino Library Github Repo
• Radiohead Arduino Library

Videos:

• Pro RF Product Video
• Cryptographic Co-processor Product Video
• Secure DIY Garage Door Opener Video

Need inspiration? Check out some of the Qwiic or IoT related tutorials!

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

Secure DIY Garage Door Opener a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1113

Introduction

If you'd like to increase the security of your garage door, or you are just interested in learning more about cryptography, then read on! At its core, this project is simply about a secure wireless button. This could be used to trigger any number of things, so we hope it can inspire message security on many other future projects.

I was surprized to learn that even if your garage door is fairly new, then you may still be vulnerable to man-in-the-middle or roll-jam attacks. With this tutorial, you can achieve an extremely high level of security utilizing ECC signatures and the SparkFun Cryptographic Co-processor.

If you'd like to read more about garage doors, here are two great articles about hacking and history.

Garage Door Hacking: What's the Deal?

A (Very) Short History of the Garage Door Opener

During my research for this project, I also came across an interesting story about garage doors in San Francisco. In 2004, military radio signals were jamming garage door openers. It seems that most garage door openers at the time were operating on the same frequency as a new military communications system (390 MHz). For more details, check out this CBS News article. After learning this, I was glad to know that my new setup is operating on 915MHz, and so shouldn't be effected.

Most communication channels are exposed to the world. Whether it's a hard wired connection or a wireless signal flying through the air, anyone can listen in and try to intercept, record and/or impersonate your signal. So how do we protect ourselves against these malicious attacks? Surprisingly, you can make a very robust solution with a couple of Pro RFs and our Cryptogrpahic Co-processors.

Suggested Reading

If you aren’t familiar with the following concepts, we recommend you read over these tutorials before continuing.

The Secure Solution

We are going to use digital signatures to add security to our system. If you want to learn more about how to use the Cryptographic Co-processor, check out this tutorial and video. These will show you the fundamental ideas behind digital signatures, walk you through how to setup each co-processor.

For the secure garage door opener example shown here, we are going to do something very similar to Example 6 in the Arduino Library. A complete cycle will follow these steps:

1. User presses button on remote to engage cycle.
2. Remote sends a "request for token".
3. Base generates a new random token (32-bytes).
4. Base sends token to remote.
5. Remote creates ECC signature on token (using its unique private key).
6. Remote sends ECC signature to base.
7. Base verifies signature using remote's public key.
8. If verified, base opens garage.

What makes this so secure is the fact that the only place in the world that can create a valid signature is inside the remote's co-processor. This is because the private key was generated randomly during configuration and will never leave the IC. If you don't have that actual piece of hardware (the remote co-processor), you will never be able to create a signature.

Also, the fact that the base creates a new random token for each cycle, allows us to prevent against man-in-the-middle and roll-jam attacks.

Wahoo! That's one heck of a secure wireless button!

Hardware Overview

For this project, we need to build up two separate circuits. One will be the remote control (that lives in my car or bike), and the second will be the base transceiver that lives inside my garage (listening for the ECC signature, and then engaging the garage door button).

Remote Control:

• Pro RF
• Duck Antennae
• Cryptographic Co-processor (for creating the ECC signature)
• Enclosure
• Button
• 400mAh Lipo Battery
• Qwiic Cable (QTY:1)

Base Transceiver:

• Pro RF
• Wire antennae
• Cryptographic Co-processor (for creating the TTL token, and verifying the ECC signature)
• SparkFun Qwiic Single Relay
• Wire antennae
• USB wall wort
• Qwiic Cable (QTY:2)

For easy one click ordering, here is a wish list. Be sure to read the entire tutorial, and then adjust as necessary.

Hardware Hookup

All of these boards use qwiic, so that made things much easier and faster to hookup.

The Remote

For the remote control, there are only 4 connections that need to be made:

The Base Transceiver

The Base Transceiver also requires hooking up just 4 connections:

Note, the order of boards in the qwiic system didn't matter, but I put the relay last so I could position it for easier access. I also soldered to the PTH pins on the bottom of the screw pin terminal, but you could choose to do a solderless connection if you like.

Integration

To engage the garage door, I opted to emulate what a human does (press the button on the wall inside). I opened up the wall-mounted controller and saw this:

Aha! I recognize those mini push button switches.Upon further inspection, I saw that there are various passive components involved:

Pretty neat how they are able to get three button control from simply two wires. I wonder if there is an ADC involved? Or maybe some sort of pulsing and time sensitive digital reads? Maybe an AC signal? What do you think?

For this project, I was only concerned with the lower momentary switch (aka the "big button"). From looking at the circuit board with backlight as shown above, I was able to see that the lower button simply connects the two leads together directly without any extra passives involved. With this in mind, I decided to use a relay and run it in parallel with the switch. I used a SparkFun Qwiic Single Relay to engage this button from my Arduino. I know this is probably overkill for the amount of current this will ever see, but I liked that this solution would be very easy to connect/control using qwiic and was a sure bet in emulating the button.

For the connection to the garage door wall-mounted button, I chose to open it up and solder to the connection points on either side of the button. After doing so, I actually realized that you could "tap" into the two wires out to the button anywhere in the line and potentially use the screw pin terminals on the relay for a solder-less connection point. Nevertheless, I used a couple XT-60 connectors on the lines, and this makes it pretty easy to take apart if necessary for re-programming.

Power Considerations

In order to save power on the remote control, I opted to put a momentary push button in series on the power input. This way, power would only be connected when I wanted to open the garage door. Otherwise, it would remain completely off. Also, with a more traditional DPST switch, we'd me more likely to accidentally leave it switched on and drain the battery. Luckily, the ProRF has a couple headers already in the design for an external switch.

Now I wanted to consider how much power is actually being used during each attempt to open the garage door. I hooked up an SparkFun RedBoard Artemis and a Zio Current and Voltage Sensor - INA219 (Qwiic), and I had some data streaming in no time!

Here is what a complete cycle looked like on the serial plotter and monitor:

Each reading is precisely 100ms apart, so adding them all up I can see that it will use 0.065mAh per cycle.

21 readings (2100ms) at 36mA = 0.021mAh

1 reading (100ms) at 56mA = 0.002mAh

20 readings (2000ms) at 76mA = 0.042mAh

Total: 0.065mAh

Battery capacity is 400mAh

400mAh / 0.065mAh = 6,153

So according to my rough math, I think I can press this button 6153 times with this single battery. At 2 times a day, 300 days a year (600/year), that's 10 years. Even with capacity loss during storage in my car (let's say 10% each year), it'll still should last... let's see...

Year: capacity : -10% - yearly use for cycles (600 * 0.065 = ~40mAh)

Year 1 : 400 - 40 - 40 = 320

Year 2 : 320 - 32 - 40 = 248

Year 3 : 248 - 25 - 40 = 183

Year 4 : 183 - 18 - 40 = 125

Year 5 : 125 - 13 - 40 = 72

Year 6 : 72 - 7 - 40 = 25

Wahoo! Six years is pretty good. Now I just need to make sure it doesn't get squashed somewhere in my car.

Arduino Code

There are two separate sketches: one for the remote control and a second for the base transceiver. You can see both sketches in the project github repository located here:

The code used in this project was kept fairly clean by using three Arduino Libraries:

• SparkFun_ATECCX08a_Arduino_Library
• SparkFun Qwiic Relay Arduino Library Github Repo
• Radiohead Arduino Library

For help with installing each necessary Arduino library, see the individual hookup guides for the Qwiic Relay and Cryptographic Co-processor. But you can also check out a more general tutorial on Arduino library installation here:

Also, to use the SparkFun Pro RF, you will need to install the SamD boards packages. You can follow along how to do that at this section of the Pro RF Hookup Guide.

Now let's take a closer look at each individual sketch.

Remote Control Sketch

This sketch basically does everything inside its setup(). This is because, it will actually remain un-powered for most of its life. When I want to power it up and begin an entire attempt cycle, I will press the momentary button on the enclosure and this will supply power.

After setting up the RF module, the cryptographic co-processor and button, the most important thing to note is that it calls "attempt_cycle" at the very end of setup(). All the good stuff happens in there!

attempt_cycle() does essentially four things:

• Engages a cycle by sending "$$$".
• Receives 64-byte token.
• Creates the ECC signature.
• Sends Signature back to the base.

    /*
  Remote Control
  This sketch is used to create a cryptographically secure wireless controller to open you garage.
  The complete system uses SparkFun Pro RF modules, Cryptographic Co-processors, and the qwiic relay.
  Note, it also requires a base transceiver setup with separate sketch.

  See the complete tutorial here:
  https://learn.sparkfun.com/tutorials/secure-diy-garage-door-opener

  By: Pete Lewis
  SparkFun Electronics
  Date: January 13th, 2020
  License: This code is public domain but you can buy me a beer if you use this and we meet someday (Beerware license).

  Feel like supporting our work? Please buy a board from SparkFun!
  https://www.sparkfun.com/products/15573

  Some of this code is a modified version of the example provided by the Radio Head
  Library which can be found here:
  www.github.com/PaulStoffregen/RadioHeadd

  Some of this code is a modified version of the example provided by the SparkFun ATECCX08a
  Arduino Library which can be found here:
  https://github.com/sparkfun/SparkFun_ATECCX08a_Arduino_Library
*/

#include <SPI.h>

//Radio Head Library:
#include <RH_RF95.h>

// We need to provide the RFM95 module's chip select and interrupt pins to the
// rf95 instance below.On the SparkFun ProRF those pins are 12 and 6 respectively.
RH_RF95 rf95(12, 6);

int LED = 13; //Status LED is on pin 13

int packetCounter = 0; //Counts the number of packets sent
long timeSinceLastPacket = 0; //Tracks the time stamp of last packet received

// The broadcast frequency is set to 921.2, but the SADM21 ProRf operates
// anywhere in the range of 902-928MHz in the Americas.
// Europe operates in the frequencies 863-870, center frequency at 868MHz.
// This works but it is unknown how well the radio configures to this frequency:
//float frequency = 864.1;
float frequency = 921.2; //Broadcast frequency


//////////////crypto stuff

#include <SparkFun_ATECCX08a_Arduino_Library.h> //Click here to get the library: http://librarymanager/All#SparkFun_ATECCX08a
#include <Wire.h>

ATECCX08A atecc;

uint8_t token[32]; // time to live token, created randomly each authentication event


/////////////

byte buf[RH_RF95_MAX_MESSAGE_LEN];

void setup()
{
  pinMode(LED, OUTPUT);

  SerialUSB.begin(115200);
  // It may be difficult to read serial messages on startup. The following line
  // will wait for serial to be ready before continuing. Comment out if not needed.
  //while (!SerialUSB);
  SerialUSB.println("RFM Client!");

  //Initialize the Radio.
  if (rf95.init() == false) {
    SerialUSB.println("Radio Init Failed - Freezing");
    while (1);
  }
  else {
    //An LED inidicator to let us know radio initialization has completed.
    //SerialUSB.println("Transmitter up!");
    //digitalWrite(LED, HIGH);
    //delay(500);
    //digitalWrite(LED, LOW);
    //delay(500);
  }

  // Set frequency
  rf95.setFrequency(frequency);

  // The default transmitter power is 13dBm, using PA_BOOST.
  // If you are using RFM95/96/97/98 modules which uses the PA_BOOST transmitter pin, then
  // you can set transmitter powers from 5 to 23 dBm:
  // Transmitter power can range from 14-20dbm.
  rf95.setTxPower(14, false);

  pinMode(5, INPUT_PULLUP);

  Wire.begin();

  if (atecc.begin() == true)
  {
    SerialUSB.println("Successful wakeUp(). I2C connections are good.");
  }
  else
  {
    SerialUSB.println("Device not found. Check wiring.");
    while (1); // stall out forever
  }

  attempt_cycle();

}


void loop()
{

  if (digitalRead(5) == LOW)
  {
//    attempt_cycle();
  }
  delay(10); // button debounce
}


void printBuf64()
{
  SerialUSB.println();
  SerialUSB.println("uint8_t buf[64] = {");
  for (int i = 0; i < 32 ; i++)
  {
    SerialUSB.print("0x");
    if ((buf[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(buf[i], HEX);
    if (i != 31) SerialUSB.print(", ");
    if ((31 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void printToken()
{
  SerialUSB.println();
  SerialUSB.println("uint8_t token[32] = {");
  for (int i = 0; i < sizeof(token) ; i++)
  {
    SerialUSB.print("0x");
    if ((token[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(token[i], HEX);
    if (i != 31) SerialUSB.print(", ");
    if ((31 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}


// Note, in Example4_Alice we are printing the signature we JUST created,
// and it lives inside the library as a public array called "atecc.signature"
void printSignature()
{
  SerialUSB.println("uint8_t signature[64] = {");
  for (int i = 0; i < sizeof(atecc.signature) ; i++)
  {
    SerialUSB.print("0x");
    if ((atecc.signature[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(atecc.signature[i], HEX);
    if (i != 63) SerialUSB.print(", ");
    if ((63 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void attempt_cycle()
{
  SerialUSB.println("Sending message");

  //Send a message to the other radio
  uint8_t toSend[] = "$$$";
  //sprintf(toSend, "Hi, my counter is: %d", packetCounter++);
  rf95.send(toSend, sizeof(toSend));
  rf95.waitPacketSent();

  // Now wait for a reply

  byte len = sizeof(buf);

  if (rf95.waitAvailableTimeout(2000)) {
    // Should be a reply message for us now
    if (rf95.recv(buf, &len)) {
      SerialUSB.print("Got reply: ");
      printBuf64();
      for (int i = 0 ; i < 32 ; i++) token[i] = buf[i]; // read in token from buffer.
      printToken(); // nice debug to see what token we just sent. see function below

      boolean sigStat = false;
      sigStat = atecc.createSignature(token); // by default, this uses the private key securely stored and locked in slot 0.

      SerialUSB.print("sigStat: ");
      SerialUSB.println(sigStat);

      //printSignature();


      // Copy our signature from library array to local toSend array
      //for (int i = 0 ; i < 64 ; i++) toSend[i] = atecc.signature[i]; // store locally

      //Send signature to the other radio
      rf95.send(atecc.signature, sizeof(atecc.signature));
      rf95.waitPacketSent();
      SerialUSB.println("Sent signature");
      //SerialUSB.println((char*)buf);
      //SerialUSB.print(" RSSI: ");
      //SerialUSB.print(rf95.lastRssi(), DEC);
    }
    else {
      SerialUSB.println("Receive failed");
    }
  }
  else {
    SerialUSB.println("No reply, is the receiver running?");
  }
  delay(500);
}

Base Transceiver Sketch

This sketch is very similar to the first Example Sketch in our hookup guide for the Pro RF: Point to Point Radio Arduino Examples In fact, that's were I started from. And then I added in the necessary libraries for the Cryptographic chip and the qwiic relay. And then I stole some code from each of their initial examples. A whole lot of copy/paste going on. Isn't that convenient, Gromit!

Inside the main loop, the Base does the following:

• Listens to incoming messages.
• If it receives a "$$$", then create a new random token and send it to remote.
• Listens for a signature from remote.
• Receives 64-byte signature.
• Verifies signature.
• If valid, trigger relay to "close" for 500ms, emulating a button press.
• If success hasn't happened within 1 second, destroy token. This protects against repeater attacks.

Note, whenever the Base hears any message come in, it checks for the "$$$". This will tell it if the message is an request or a signature. If it doesn't see "$$$" then it pulls in the next 64 bytes and attempts to verify the signature.

/*
  Base Transceiver
  This sketch is used to create a cryptographically secure wireless controller to open you garage.
  The complete system uses SparkFun Pro RF modules, Cryptographic Co-processors, and the qwiic relay.
  Note, it also requires a remote control setup with separate sketch.

  See the complete tutorial here:
  https://learn.sparkfun.com/tutorials/secure-diy-garage-door-opener

  By: Pete Lewis
  SparkFun Electronics
  Date: January 13th, 2020
  License: This code is public domain but you can buy me a beer if you use this and we meet someday (Beerware license).

  Feel like supporting our work? Please buy a board from SparkFun!
  https://www.sparkfun.com/products/15573

  Some of this code is a modified version of the example provided by the Radio Head
  Library which can be found here:
  www.github.com/PaulStoffregen/RadioHeadd

  Some of this code is a modified version of the example provided by the SparkFun ATECCX08a
  Arduino Library which can be found here:
  https://github.com/sparkfun/SparkFun_ATECCX08a_Arduino_Library

  Some of the code is a modified version of the example provided by the SparkFun Qwiic
  Relay Arduino Library which can be found here:
  https://github.com/sparkfun/SparkFun_Qwiic_Relay_Arduino_Library
*/



#include <SPI.h>

//Radio Head Library:
#include <RH_RF95.h>

// We need to provide the RFM95 module's chip select and interrupt pins to the
// rf95 instance below.On the SparkFun ProRF those pins are 12 and 6 respectively.
RH_RF95 rf95(12, 6);

int LED = 13; //Status LED on pin 13

int successLED = 3; // green
int failLED = 4; // red
int statLED = 2; // blue

int packetCounter = 0; //Counts the number of packets sent
long timeSinceLastPacket = 0; //Tracks the time stamp of last packet received
// The broadcast frequency is set to 921.2, but the SADM21 ProRf operates
// anywhere in the range of 902-928MHz in the Americas.
// Europe operates in the frequencies 863-870, center frequency at
// 868MHz.This works but it is unknown how well the radio configures to this frequency:
//float frequency = 864.1;
float frequency = 921.2;

uint8_t buf[RH_RF95_MAX_MESSAGE_LEN];


////////////////relay

#include "SparkFun_Qwiic_Relay.h"

#define RELAY_ADDR 0x18 // Alternate address 0x19


Qwiic_Relay relay(RELAY_ADDR);

////////////////

/////////////////crypto

#include <SparkFun_ATECCX08a_Arduino_Library.h> //Click here to get the library: http://librarymanager/All#SparkFun_ATECCX08a
#include <Wire.h>

ATECCX08A atecc;

uint8_t token[32]; // time to live token, created randomly each authentication event

uint8_t signature[64]; // incoming signature from Alice

int headerCount = 0; // used to count incoming "$", when we reach 3 we know it's a good fresh new message.

// Alice's public key.
// Note, this will be unique to each co-processor, so your will be different.
// copy/paste Alice's true unique public key from her terminal printout in Example6_Challenge_Alice.

uint8_t AlicesPublicKey[64] = {
  0x38, 0xD6, 0xE5, 0x49, 0xAC, 0x57, 0x2D, 0x1F, 0xD0, 0x58, 0x0A, 0xE8, 0x59, 0xB8, 0xF8, 0x20,
  0x1E, 0x0A, 0x7E, 0x8D, 0x5B, 0x7D, 0xD9, 0x8A, 0x26, 0xAF, 0x88, 0x73, 0x6D, 0x8C, 0xB7, 0x2D,
  0x8D, 0x3A, 0xB9, 0x5F, 0x60, 0x9D, 0x3F, 0x49, 0x72, 0xF1, 0x44, 0x74, 0x82, 0x3F, 0x7B, 0xCF,
  0x1F, 0x18, 0xD3, 0xA4, 0xBF, 0x62, 0x15, 0xCC, 0xAF, 0xAD, 0x7E, 0x03, 0xD8, 0xE9, 0x93, 0x7E
};

void setup()
{
  pinMode(LED, OUTPUT);
  pinMode(successLED, OUTPUT);
  pinMode(failLED, OUTPUT);
  pinMode(statLED, OUTPUT);

  SerialUSB.begin(115200);
  // It may be difficult to read serial messages on startup. The following
  // line will wait for serial to be ready before continuing. Comment out if not needed.
  //while (!SerialUSB);
  SerialUSB.println("RFM Server!");

  //Initialize the Radio.
  if (rf95.init() == false) {
    SerialUSB.println("Radio Init Failed - Freezing");
    while (1);
  }
  else {
    // An LED indicator to let us know radio initialization has completed.
    SerialUSB.println("Receiver up!");
    digitalWrite(LED, HIGH);
    delay(500);
    digitalWrite(LED, LOW);
    delay(500);
  }

  rf95.setFrequency(frequency);

  // The default transmitter power is 13dBm, using PA_BOOST.
  // If you are using RFM95/96/97/98 modules which uses the PA_BOOST transmitter pin, then
  // you can set transmitter powers from 5 to 23 dBm:
  // rf95.setTxPower(14, false);


  Wire.begin();

  if (atecc.begin() == true)
  {
    SerialUSB.println("Successful wakeUp(). I2C connections are good.");
  }
  else
  {
    SerialUSB.println("Device not found. Check wiring.");
    while (1); // stall out forever
  }

  if (!relay.begin())
  {
    Serial.println("Check connections to Qwiic Relay.");
    while (1); // stall out forever
  }
  else
  {
    Serial.println("Qwiic Relay is ready to go.");
  }

}

void loop()
{
  if (rf95.available()) {
    // Should be a message for us now

    uint8_t len = sizeof(buf);

    if (rf95.recv(buf, &len)) {
      digitalWrite(LED, HIGH); //Turn on status LED
      timeSinceLastPacket = millis(); //Timestamp this packet

      SerialUSB.print("Got message: ");
      printBuf64();
      //SerialUSB.print(" RSSI: ");
      //SerialUSB.print(rf95.lastRssi(), DEC);
      SerialUSB.println();

      // if message from Alice is "$$$", Send a random token for her to sign.
      if (buf[0] == '$' && buf[1] == '$' && buf[2] == '$')
      {
        SerialUSB.println("Received $$$. Creating a new random TTL-token now...");

        // update library instance public variable.
        atecc.updateRandom32Bytes();

        uint8_t toSend[32];
        // copy from library public variable into our local variable
        for (int i = 0 ; i < 32 ; i++)
        {
          token[i] = atecc.random32Bytes[i]; // store locally
        }

        rf95.send(token, sizeof(token));
        rf95.waitPacketSent();
        SerialUSB.println("Sent token");
        digitalWrite(LED, LOW); //Turn off status LED
      }
      else // this means Alice just sent us a signature
      {
        SerialUSB.println("Received signature. Verifying now...");
        for (int i = 0 ; i < 64 ; i++) signature[i] = buf[i]; // read in signature from buffer.
        printSignature();
        // Let's verirfy!
        if (atecc.verifySignature(token, signature, AlicesPublicKey))
        {
          SerialUSB.println("Success! Signature Verified.");
          // Let's turn on the relay...
          relay.turnRelayOn();
          delay(1000);
          // Let's turn that relay off...
          relay.turnRelayOff();
          blinkStatus(successLED);
        }
        else
        {
          SerialUSB.println("Verification failure.");
          blinkStatus(failLED);
        }
      }

    }
    else
      SerialUSB.println("Recieve failed");
  }
  //Turn off status LED if we haven't received a packet after 1s
  if (millis() - timeSinceLastPacket > 1000) {
    digitalWrite(LED, LOW); //Turn off status LED
    timeSinceLastPacket = millis(); //Don't write LED but every 1s
    clearBuf();
    // destory token, to require a new cycle if this doesn't complete within 1 second
    for (int i = 0 ; i < 32 ; i++)
    {
      token[i] = 0x00;
    }
  }
}


void printSignature()
{
  SerialUSB.println("uint8_t signature[64] = {");
  for (int i = 0; i < sizeof(signature) ; i++)
  {
    SerialUSB.print("0x");
    if ((signature[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(signature[i], HEX);
    if (i != 63) SerialUSB.print(", ");
    if ((63 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void printBuf64()
{
  SerialUSB.println();
  SerialUSB.println("uint8_t buf[64] = {");
  for (int i = 0; i < 64 ; i++)
  {
    SerialUSB.print("0x");
    if ((buf[i] >> 4) == 0) SerialUSB.print("0"); // print preceeding high nibble if it's zero
    SerialUSB.print(buf[i], HEX);
    if (i != 63) SerialUSB.print(", ");
    if ((63 - i) % 16 == 0) SerialUSB.println();
  }
  SerialUSB.println("};");
  SerialUSB.println();
}

void clearBuf()
{
  for (int i = 0; i < 64 ; i++) buf[i] = 0x00;
}

void blinkStatus(int LED)
{
  digitalWrite(LED, HIGH);
  delay(2000);
  digitalWrite(LED, LOW);
  delay(500);
}

Resources & Going Further

Now that you've incorporated ECC authentication security into your garage door opener, you can add security to any future project they may need it. How about your internet-connected front door?

For more information, check out the resources below:

Project Source Code:

• Project GitHub Repository

Hookup Guides:

• SAMD21 Pro RF Hookup Guide
• Cryptographic Co-Processor ATECC508A (Qwiic) Hookup Guide
• Qwiic Single Relay Hookup Guide

Arduino Libraries:

• SparkFun_ATECCX08a_Arduino_Library
• SparkFun Qwiic Relay Arduino Library Github Repo
• Radiohead Arduino Library

Videos:

• Pro RF Product Video
• Cryptographic Co-processor Product Video
• Secure DIY Garage Door Opener Video

Need inspiration? Check out some of the Qwiic or IoT related tutorials!

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

RED-V RedBoard Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1032

Introduction

SparkFun is pleased to welcome a whole new instruction set architecture (ISA) to its family, the RISC-V ISA (pronounced “risk-five”), and along with it, introduce the RED-V RedBoard (pronounced “red-five”). In this tutorial, we'll be focusing on the hardware.

added to your cart!

SparkFun RED-V RedBoard - SiFive RISC-V FE310 SoC

In stock DEV-15594

The RED-V RedBoard from SparkFun is a low-cost, Arduino-compatible development board featuring the Freedom E310 which brings …

$39.95

2

FavoritedFavorite4

Wish List

What sets the RISC-V ISA from the rest is that it is completely open-source; including the instruction set architecture (ISA). That means anyone can make full use the microcontroller without requiring royalties, licenses, or non-disclosure agreements (NDAs). The RED-V comes in the familiar Arduino Uno form factor and includes the SiFive Freedom E310 core, 32MB of QSPI flash, an NXP K22 ARM Cortex-M4 for USB connectivity and operating as a JTAG interface, and a Qwiic connector.

Required Materials

To follow along with this tutorial, you will need the following materials and software. You may not need everything though depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary. Here is what you would need to get started:

added to your cart!

SparkFun RED-V RedBoard - SiFive RISC-V FE310 SoC

In stock DEV-15594

The RED-V RedBoard from SparkFun is a low-cost, Arduino-compatible development board featuring the Freedom E310 which brings …

$39.95

2

FavoritedFavorite4

Wish List

added to your cart!

USB 3.1 Cable A to C - 3 Foot

Out of stock CAB-14743

USB C is fantastic. But until we have converted all our hubs, chargers, and ports over to USB C this is the cable you're goin…

$4.95

2

FavoritedFavorite4

Wish List

• RED-V - You'll definitely need this; otherwise, you are probably on the wrong tutorial page (wink).
• USB 3.1 Cable A to C - 3 Foot - The USB interface serves two purposes: it powers the board and allows you to upload programs to it. (You might even have a few of these in you drawer!)

You Will Also Need

To utilize all the features of the development board, you may need the following tools and accessories. If you would like to modify the jumpers on the board, you will need soldering equipment.

added to your cart!

Solder Lead Free - 100-gram Spool

In stock TOL-09325

This is your basic spool of lead free solder with a water soluble resin core. 0.031" gauge and 100 grams. This is a good spoo…

$7.95

7

FavoritedFavorite28

Wish List

added to your cart!

Chip Quik No-Clean Flux Pen - 10mL

In stock TOL-14579

This 10mL no-clean flux pen from Chip Quik is great for all of your solder, de-solder, rework, and reflow purposes!

$7.95

2

FavoritedFavorite17

Wish List

added to your cart!

Weller WLC100 Soldering Station

Only 1 left! TOL-14228

The WLC100 from Weller is a versatile 5 watt to 40 watt soldering station that is perfect for hobbyists, DIYers and students.…

$44.95

1

FavoritedFavorite13

Wish List

Jumper Modification

If you would like to modify the jumpers on the board, you will need soldering equipment.

added to your cart!

Solder Lead Free - 100-gram Spool

In stock TOL-09325

This is your basic spool of lead free solder with a water soluble resin core. 0.031" gauge and 100 grams. This is a good spoo…

$7.95

7

FavoritedFavorite28

Wish List

added to your cart!

Chip Quik No-Clean Flux Pen - 10mL

In stock TOL-14579

This 10mL no-clean flux pen from Chip Quik is great for all of your solder, de-solder, rework, and reflow purposes!

$7.95

2

FavoritedFavorite17

Wish List

added to your cart!

Weller WLC100 Soldering Station

Only 1 left! TOL-14228

The WLC100 from Weller is a versatile 5 watt to 40 watt soldering station that is perfect for hobbyists, DIYers and students.…

$44.95

1

FavoritedFavorite13

Wish List

Qwiic Example

If you would like to follow along with the examples below to interact with the physical world, you will also need the following items:

added to your cart!

Qwiic Cable - 100mm

In stock PRT-14427

This is a 100mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite12

Wish List

added to your cart!

SparkFun Qwiic 12 Bit ADC - 4 Channel (ADS1015)

In stock DEV-15334

The SparkFun Qwiic 12 Bit ADC can provide four channels of I²C controlled ADC input to your Qwiic enabled project.

$9.95

FavoritedFavorite5

Wish List

added to your cart!

Magnetic Screwdriver Set (20 Piece)

In stock TOL-15003

This is a 20 piece screwdriver set that magnetically keeps each of the unused bits secured inside of a thin case that easily …

$6.95

1

FavoritedFavorite3

Wish List

Segger Programmers

If you would like to debug or flash your processor on your own, here are some of our SEGGER Programmers. We also recommend getting the 1.27mm header pins with some jumper wires to connect. Depending on the programmer that you use, you may need to use a combination of wire wrap and IC hooks to connect.

added to your cart!

J-Link EDU Mini Programmer

In stock PGM-15345

Tiny J-Link programmer for programming any ARM microconroller. Comes with an educational/ non-commercial license.

$18.00

1

FavoritedFavorite6

Wish List

added to your cart!

J-Link EDU Base Programmer

Only 11 left! PGM-15346

J-Link programmer for programming any ARM microconroller. Comes with an educational/ non-commercial license.

$60.00

FavoritedFavorite2

Wish List

added to your cart!

J-Link BASE Compact Programmer

Only 4 left! PGM-15347

Compact J-Link programmer for programming any ARM microconroller.

$378.00

FavoritedFavorite2

Wish List

added to your cart!

Header - 2x5 Pin (Male, 1.27mm)

In stock PRT-15362

This is a super small, 2x5 pin male PTH header. This header is in the common configuration for JTAG applications.

$1.50

FavoritedFavorite2

Wish List

Suggested Reading

Before continuing on with this tutorial, you may want to familiarize yourself with some of these topics if they’re unfamiliar to you.

Hardware Overview

Power & Programming

There are a few different ways to power the SparkFun RED-V RedBoard:

• USB-C
• barrel jack connector
• power pins broken out on the edge of the board

The easiest way (which will also allow you to program your board) is to simply plug it into your computer via USB-C. This will provide 5V to the board and will also allow you access to the super cool USB-to-JTAG interface for programming. Once you've programmed your RED-V however, you may want to have it running off of a different power supply. If you use a wall wart on the USB-C connector, make sure it outputs a regulated 5V DC. You can also use the black barrel jack, in which case you'll need any wall adapter between 7 & 15 Volts DC. Or you can also power the board through the header pins broken out on the edge of the board. If you are using VIN and GND, follow the same practice as using a wall adapter and stick to between 7 & 15 Volts. If you are using 5V and GND or 3v3 and GND, make sure that your voltage is regulated when applying power to the 5V or 3.3V pins, respectively.

Always-On Core

The FE310 contains an Always-On (AON) block that allows easy power control of the FE310. It includes its own real-time clock and is also attached to the WAKE button on the board. This allows you to put the FE310 to sleep and wake it up upon a time-generated or user-generated interrupt.

Buttons

The RED-V has two buttons: a RESET button and a WAKE button. The RESET button is pretty self explanatory and is used to reset the FE310. A single tap of the RESET button will run the code loaded onto the FE310's QSPI flash. A quick double tap will put the FE310 into safe bootloader mode, which will allow you to flash new code to the RED-V if you've managed to really mess things up (i.e. Oops I put the core to sleep and forgot to add a way to wake it up). The pin is also broken out on the edge of the board. Adding a jumper wire from this pin to GND will reset the board as well.

The RED-V is also equipped with an Always-On or AON core (mentioned above) which can be programmed to shut down the main core of the FE310 and wake it up upon a button-generated or user-generated interrupt. The WAKE button can be configured in software to wake the FE310 from deep sleep. This button is also broken out to the header pin nearest the barrel jack if you'd like to use an external source to wake the FE310. Adding a jumper wire from this pin to GND will wake the board as well.

Jumpers

The FE310 has a few jumpers as well, all of which are open by default. The two jumpers located next to the I2C label is for the I²C pull-up resistors. These resistors are not attached by default as there are I²C pull-up resistors on all SparkFun Qwiic slaves. If you're using a 3^rd party board, you may need to close these jumper by the Qwiic connector to attach the pull-ups to the I²C bus. The jumper by the USB-C connector is for bypassing the 0.5A PTC fuse. This is for special cases where you need a lot current. Most of the time, you can leave this jumper open.

Dimensions

The RED-V RedBoard uses the Arduino Uno footprint. There are four mounting holes on the board.

Hardware Hookup

For the scope of the tutorial, you'll use a USB C cable to power, upload code, and send serial to the board. Simply connect the computer's USB port and the RED-V. The board uses standard Arduino Uno R3 footprint with female headers to stack Arduino shields and easily connect prototyped circuits on breadboards with jumper wires.

Software Development Guide

There are a few environments to get started with the RED-V. For information about programming the RED-V RedBoard, check out the following tutorial.

Resources and Going Further

Now that you've successfully got started with your RED-V RedBoard, it's time to incorporate it into your own project! For more information, check out the resources below:

• Schematic (PDF)
• Eagle Files (ZIP)
• Dimensions
• Qwiic Landing Page
• RISC-V
  • Specifications
  • Software Status
  • Cores
• SiFive
  • E310-G002
    • Datasheet (PDF)
    • Manual (PDF)
  • Freedom Studio and E SDK
  • Freedom Studio User Manual (PDF)
• GitHub Hardware Repo
• SFE Product Showcase

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

RED-V Thing Plus Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1099

Introduction

SparkFun is pleased to welcome its a whole new instruction set architecture (ISA) to its family, the RISC-V ISA (pronounced “risk-five”), and along with it, introduce the RED-V Thing Plus (pronounced “red-five”). In this tutorial, we'll be focusing on the hardware.

added to your cart!

SparkFun RED-V Thing Plus - SiFive RISC-V FE310 SoC

In stock DEV-15799

The RED-V Thing Plus from SparkFun is a low-cost, Arduino-compatible development board featuring the Freedom E310 which bring…

$29.95

FavoritedFavorite5

Wish List

What sets the RISC-V ISA from the rest is that it is completely open-source; including the instruction set architecture (ISA). That means anyone can make full use the microcontroller without requiring royalties, licenses, or non-disclosure agreements (NDAs). The RED-V comes in the familiar SparkFun Thing Plus form factor and includes the SiFive Freedom E310 core, 32MB of QSPI flash, an NXP K22 ARM Cortex-M4 for USB connectivity and operating as a JTAG interface, and a Qwiic connector.

Required Materials

To follow along with this tutorial, you will need the following materials and software. You may not need everything though depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary. Here is what you would need to get started:

added to your cart!

SparkFun RED-V Thing Plus - SiFive RISC-V FE310 SoC

In stock DEV-15799

The RED-V Thing Plus from SparkFun is a low-cost, Arduino-compatible development board featuring the Freedom E310 which bring…

$29.95

FavoritedFavorite5

Wish List

added to your cart!

USB 3.1 Cable A to C - 3 Foot

Out of stock CAB-14743

USB C is fantastic. But until we have converted all our hubs, chargers, and ports over to USB C this is the cable you're goin…

$4.95

2

FavoritedFavorite4

Wish List

• RED-V Thing Plus - You'll definitely need this; otherwise, you are probably on the wrong tutorial page (wink).
• USB 3.1 Cable A to C - 3 Foot - The USB interface serves two purposes: it powers the board and allows you to upload programs to it. (You might even have a few of these in you drawer!)

You Will Also Need

To utilize all the features of the development board, you may need the following tools and accessories.

Jumper ModificationHeaders & Accessories

Jumper Modification

If you would like to modify the jumpers on the board, you will need soldering equipment.

added to your cart!

Solder Lead Free - 100-gram Spool

In stock TOL-09325

This is your basic spool of lead free solder with a water soluble resin core. 0.031" gauge and 100 grams. This is a good spoo…

$7.95

7

FavoritedFavorite28

Wish List

added to your cart!

Weller WLC100 Soldering Station

Only 1 left! TOL-14228

The WLC100 from Weller is a versatile 5 watt to 40 watt soldering station that is perfect for hobbyists, DIYers and students.…

$44.95

1

FavoritedFavorite13

Wish List

added to your cart!

Chip Quik No-Clean Flux Pen - 10mL

In stock TOL-14579

This 10mL no-clean flux pen from Chip Quik is great for all of your solder, de-solder, rework, and reflow purposes!

$7.95

2

FavoritedFavorite17

Wish List

Qwiic Example

If you would like to follow along with the examples below to interact with the physical world, you will also need the following items:

added to your cart!

Qwiic Cable - 100mm

In stock PRT-14427

This is a 100mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite12

Wish List

added to your cart!

SparkFun Qwiic 12 Bit ADC - 4 Channel (ADS1015)

In stock DEV-15334

The SparkFun Qwiic 12 Bit ADC can provide four channels of I²C controlled ADC input to your Qwiic enabled project.

$9.95

FavoritedFavorite5

Wish List

added to your cart!

Magnetic Screwdriver Set (20 Piece)

In stock TOL-15003

This is a 20 piece screwdriver set that magnetically keeps each of the unused bits secured inside of a thin case that easily …

$6.95

1

FavoritedFavorite3

Wish List

Headers & Accessories

If you would like to add headers to your board, check out some of the following items:

added to your cart!

Break Away Headers - Straight

Out of stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers.

$1.50

20

FavoritedFavorite99

Wish List

added to your cart!

SparkFun Beginner Tool Kit

22 available TOL-14681

This assortment of tools is great for those of you who need a solid set of tools to start your workbench on the right foot!

$54.95

FavoritedFavorite3

Wish List

added to your cart!

Feather Stackable Header Kit

In stock PRT-15187

These stackable headers are made to work with the [SparkFun ESP32 Thing Plus](https://www.sparkfun.com/products/14689) to con…

$1.50

FavoritedFavorite2

Wish List

Below is a sample selection of our other headers and soldering tools in our catalog. For a full selection of our available Headers or Soldering Tools, click on the associated link.

added to your cart!

Break Away Headers - Straight

Out of stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers.

$1.50

20

FavoritedFavorite99

Wish List

added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.50

7

FavoritedFavorite54

Wish List

added to your cart!

Arduino Stackable Header Kit - R3

Out of stock PRT-11417

These headers are made to work with the Arduino Uno R3, Leonardo and new Arduino boards going forward. They are the perfect h…

$1.50

12

FavoritedFavorite57

Wish List

added to your cart!

Break Away Male Headers - Right Angle

In stock PRT-00553

A row of right angle male headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custo…

$1.95

4

FavoritedFavorite35

Wish List

added to your cart!

Insulated Silicone Soldering Mat

In stock TOL-14672

With this Insulated Silicone Soldering Mat you will be provided with the means to protect your desktop, soldering station, or…

$9.95

5

FavoritedFavorite46

Wish List

added to your cart!

Weller WE1010 Soldering Station

Only 3 left! TOL-14734

The WE1010 from Weller is a powerful 70 watt soldering station that is perfect for passionate hobbyists, DIYers, and anyone w…

$129.00

1

FavoritedFavorite11

Wish List

added to your cart!

Solder Lead Free - 100-gram Spool

In stock TOL-09325

This is your basic spool of lead free solder with a water soluble resin core. 0.031" gauge and 100 grams. This is a good spoo…

$7.95

7

FavoritedFavorite28

Wish List

added to your cart!

Solder - 1/4lb Spool (0.020") Special Blend

In stock TOL-10242

We don't want to hype this solder TOO much, but this could possibly be the best solder in the world. There, we've said it. Th…

$29.95

7

FavoritedFavorite12

Wish List

Segger Programmers

If you would like to debug or flash your processor on your own, here are some of our SEGGER Programmers. Depending on the programmer that you use, you may need to use a combination of wire wrap and IC hooks to connect.

added to your cart!

J-Link EDU Mini Programmer

In stock PGM-15345

Tiny J-Link programmer for programming any ARM microconroller. Comes with an educational/ non-commercial license.

$18.00

1

FavoritedFavorite6

Wish List

added to your cart!

J-Link EDU Base Programmer

Only 11 left! PGM-15346

J-Link programmer for programming any ARM microconroller. Comes with an educational/ non-commercial license.

$60.00

FavoritedFavorite2

Wish List

added to your cart!

J-Link BASE Compact Programmer

Only 4 left! PGM-15347

Compact J-Link programmer for programming any ARM microconroller.

$378.00

FavoritedFavorite2

Wish List

Suggested Reading

Before continuing on with this tutorial, you may want to familiarize yourself with some of these topics if they’re unfamiliar to you.

Hardware Overview

Power & Programming

There are a few different ways to power the SparkFun RED-V Thing Plus:

• USB-C
• JST connector (battery power)
• power pins broken out on the edge of the board

The easiest way (which will also allow you to program your board) is to simply plug it into your computer via USB-C. This will provide 5V to the board and will also allow you access to the super cool USB-to-JTAG interface for programming. Once you've programmed your RED-V however, you may want to have it running off of a different power supply. If you use a wall wart on the USB-C connector, make sure it outputs a regulated 5V DC. You can also use the black JST connector to provide battery power from a LiPo battery. There is an on-board LiPo charger with the current rate set to 500mA. Make sure to use LiPo batteries that have a capacity greater than 500mAh when charging. If you decide to power the board via the VUSB or VBAT pins, make sure to not exceed 6.5V since this is the absolute maximum for the 3.3V voltage regulator. Or you can power the board through the breakout pins on the edge of the board. If you are using 3V3 and GND, make sure that your voltage is regulated when applying power to the pin.

Always-On Core

The FE310 contains an Always-On (AON) block that allows easy power control of the FE310. It includes its own real-time clock and is also attached to the WAKE button on the board. This allows you to put the FE310 to sleep and wake it up upon a time-generated or user-generated interrupt.

Buttons

The RED-V has two buttons: a RESET button and a WAKE button. The RESET button is pretty self explanatory and is used to reset the FE310. A single tap of the RESET button will run the code loaded onto the FE310's QSPI flash. A quick double tap will put the FE310 into safe bootloader mode, which will allow you to flash new code to the RED-V if you've managed to really mess things up (i.e. Oops I put the core to sleep and forgot to add a way to wake it up). The pin is also broken out on the edge of the board. Adding a jumper wire from this pin to GND will reset the board as well.

The RED-V is also equipped with an Always-On or AON core (mentioned above) which can be programmed to shut down the main core of the FE310 and wake it up upon a button-generated or user-generated interrupt. The WAKE button can be configured in software to wake the FE310 from deep sleep.

Jumpers

The FE310 has a few jumpers as well, all of which are open by default. The two jumpers located next to the I2C label is for the I²C pull-up resistors. These resistors are not attached by default as there are I²C pull-up resistors on all SparkFun Qwiic slaves. If you're using a 3^rd party board, you may need to close these jumper by the Qwiic connector to attach the pull-ups to the I²C bus. The jumper by the USB-C connector (next to the Segger logo) is for bypassing the 0.5A PTC fuse. This is for special cases where you need a lot current. If you need to connect the NC pin to GND, you can also add a solder jumper on the pads as well. Most of the time, you can leave the bypass and NC jumpers open.

Dimensions

The RED-V Thing Plus measures at 2.3"x0.90".

Hardware Hookup

For the scope of the tutorial, you'll use a USB C cable to power, upload code, and send serial to the board. Simply connect the computer's USB port and the RED-V Thing Plus. The board uses standard Thing Plus footprint.

The headers were left off the board to allow users the flexibility of connecting any type of 0.1" header to the board. For temporary connections to the I/O pins, you could use IC hooks to test out the pins. However, you'll need to solder headers or wires of your choice to the board for a secure connection. Here are a few tutorials to connect to the PTH pads depending on your personal preference.

Software Development Guide

There are a few environments to get started with the RED-V. For information about programming the RED-V Thing Plus, check out the following tutorial.

Resources and Going Further

Now that you've successfully got started with your RED-V Thing Plus, it's time to incorporate it into your own project! For more information, check out the resources below:

• Schematic (PDF)
• Eagle Files (ZIP)
• Dimensions
• Qwiic Landing Page
• RISC-V
  • Specifications
  • Software Status
  • Cores
• SiFive
  • E310-G002
    • Datasheet (PDF)
    • Manual (PDF)
  • Freedom Studio and E SDK
  • Freedom Studio User Manual (PDF)
• GitHub Hardware Repo
• SFE Product Showcase

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

RED-V RedBoard Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1032

Introduction

SparkFun is pleased to welcome a whole new instruction set architecture (ISA) to its family, the RISC-V ISA (pronounced “risk-five”), and along with it, introduce the RED-V RedBoard (pronounced “red-five”). In this tutorial, we'll be focusing on the hardware.

added to your cart!

SparkFun RED-V RedBoard - SiFive RISC-V FE310 SoC

In stock DEV-15594

The RED-V RedBoard from SparkFun is a low-cost, Arduino-compatible development board featuring the Freedom E310 which brings …

$39.95

2

FavoritedFavorite4

Wish List

What sets the RISC-V ISA from the rest is that it is completely open-source; including the instruction set architecture (ISA). That means anyone can make full use the microcontroller without requiring royalties, licenses, or non-disclosure agreements (NDAs). The RED-V comes in the familiar Arduino Uno form factor and includes the SiFive Freedom E310 core, 32MB of QSPI flash, an NXP K22 ARM Cortex-M4 for USB connectivity and operating as a JTAG interface, and a Qwiic connector.

Required Materials

To follow along with this tutorial, you will need the following materials and software. You may not need everything though depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary. Here is what you would need to get started:

added to your cart!

SparkFun RED-V RedBoard - SiFive RISC-V FE310 SoC

In stock DEV-15594

The RED-V RedBoard from SparkFun is a low-cost, Arduino-compatible development board featuring the Freedom E310 which brings …

$39.95

2

FavoritedFavorite4

Wish List

added to your cart!

USB 3.1 Cable A to C - 3 Foot

Out of stock CAB-14743

USB C is fantastic. But until we have converted all our hubs, chargers, and ports over to USB C this is the cable you're goin…

$4.95

2

FavoritedFavorite4

Wish List

• RED-V - You'll definitely need this; otherwise, you are probably on the wrong tutorial page (wink).
• USB 3.1 Cable A to C - 3 Foot - The USB interface serves two purposes: it powers the board and allows you to upload programs to it. (You might even have a few of these in you drawer!)

You Will Also Need

To utilize all the features of the development board, you may need the following tools and accessories. If you would like to modify the jumpers on the board, you will need soldering equipment.

added to your cart!

Solder Lead Free - 100-gram Spool

In stock TOL-09325

This is your basic spool of lead free solder with a water soluble resin core. 0.031" gauge and 100 grams. This is a good spoo…

$7.95

7

FavoritedFavorite28

Wish List

added to your cart!

Weller WLC100 Soldering Station

Out of stock TOL-14228

The WLC100 from Weller is a versatile 5 watt to 40 watt soldering station that is perfect for hobbyists, DIYers and students.…

$44.95

1

FavoritedFavorite13

Wish List

added to your cart!

Chip Quik No-Clean Flux Pen - 10mL

In stock TOL-14579

This 10mL no-clean flux pen from Chip Quik is great for all of your solder, de-solder, rework, and reflow purposes!

$7.95

2

FavoritedFavorite17

Wish List

Jumper Modification

If you would like to modify the jumpers on the board, you will need soldering equipment.

added to your cart!

Solder Lead Free - 100-gram Spool

In stock TOL-09325

This is your basic spool of lead free solder with a water soluble resin core. 0.031" gauge and 100 grams. This is a good spoo…

$7.95

7

FavoritedFavorite28

Wish List

added to your cart!

Weller WLC100 Soldering Station

Out of stock TOL-14228

The WLC100 from Weller is a versatile 5 watt to 40 watt soldering station that is perfect for hobbyists, DIYers and students.…

$44.95

1

FavoritedFavorite13

Wish List

added to your cart!

Chip Quik No-Clean Flux Pen - 10mL

In stock TOL-14579

This 10mL no-clean flux pen from Chip Quik is great for all of your solder, de-solder, rework, and reflow purposes!

$7.95

2

FavoritedFavorite17

Wish List

Qwiic Example

If you would like to follow along with the examples below to interact with the physical world, you will also need the following items:

added to your cart!

Qwiic Cable - 100mm

In stock PRT-14427

This is a 100mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite12

Wish List

added to your cart!

SparkFun Qwiic 12 Bit ADC - 4 Channel (ADS1015)

In stock DEV-15334

The SparkFun Qwiic 12 Bit ADC can provide four channels of I²C controlled ADC input to your Qwiic enabled project.

$9.95

FavoritedFavorite5

Wish List

added to your cart!

Magnetic Screwdriver Set (20 Piece)

In stock TOL-15003

This is a 20 piece screwdriver set that magnetically keeps each of the unused bits secured inside of a thin case that easily …

$6.95

1

FavoritedFavorite3

Wish List

Segger Programmers

If you would like to debug or flash your processor on your own, here are some of our SEGGER Programmers. We also recommend getting the 1.27mm header pins with some jumper wires to connect. Depending on the programmer that you use, you may need to use a combination of wire wrap and IC hooks to connect.

added to your cart!

J-Link EDU Mini Programmer

In stock PGM-15345

Tiny J-Link programmer for programming any ARM microconroller. Comes with an educational/ non-commercial license.

$18.00

1

FavoritedFavorite6

Wish List

added to your cart!

J-Link EDU Base Programmer

Only 11 left! PGM-15346

J-Link programmer for programming any ARM microconroller. Comes with an educational/ non-commercial license.

$60.00

FavoritedFavorite2

Wish List

added to your cart!

J-Link BASE Compact Programmer

Only 4 left! PGM-15347

Compact J-Link programmer for programming any ARM microconroller.

$378.00

FavoritedFavorite2

Wish List

added to your cart!

Header - 2x5 Pin (Male, 1.27mm)

In stock PRT-15362

This is a super small, 2x5 pin male PTH header. This header is in the common configuration for JTAG applications.

$1.50

FavoritedFavorite2

Wish List

Suggested Reading

Before continuing on with this tutorial, you may want to familiarize yourself with some of these topics if they’re unfamiliar to you.

Hardware Overview

Power & Programming

There are a few different ways to power the SparkFun RED-V RedBoard:

• USB-C
• barrel jack connector
• power pins broken out on the edge of the board

The easiest way (which will also allow you to program your board) is to simply plug it into your computer via USB-C. This will provide 5V to the board and will also allow you access to the super cool USB-to-JTAG interface for programming. Once you've programmed your RED-V however, you may want to have it running off of a different power supply. If you use a wall wart on the USB-C connector, make sure it outputs a regulated 5V DC. You can also use the black barrel jack, in which case you'll need any wall adapter between 7 & 15 Volts DC. Or you can also power the board through the header pins broken out on the edge of the board. If you are using VIN and GND, follow the same practice as using a wall adapter and stick to between 7 & 15 Volts. If you are using 5V and GND or 3v3 and GND, make sure that your voltage is regulated when applying power to the 5V or 3.3V pins, respectively.

Always-On Core

The FE310 contains an Always-On (AON) block that allows easy power control of the FE310. It includes its own real-time clock and is also attached to the WAKE button on the board. This allows you to put the FE310 to sleep and wake it up upon a time-generated or user-generated interrupt.

Buttons

The RED-V has two buttons: a RESET button and a WAKE button. The RESET button is pretty self explanatory and is used to reset the FE310. A single tap of the RESET button will run the code loaded onto the FE310's QSPI flash. A quick double tap will put the FE310 into safe bootloader mode, which will allow you to flash new code to the RED-V if you've managed to really mess things up (i.e. Oops I put the core to sleep and forgot to add a way to wake it up). The pin is also broken out on the edge of the board. Adding a jumper wire from this pin to GND will reset the board as well.

The RED-V is also equipped with an Always-On or AON core (mentioned above) which can be programmed to shut down the main core of the FE310 and wake it up upon a button-generated or user-generated interrupt. The WAKE button can be configured in software to wake the FE310 from deep sleep. This button is also broken out to the header pin nearest the barrel jack if you'd like to use an external source to wake the FE310. Adding a jumper wire from this pin to GND will wake the board as well.

Jumpers

The FE310 has a few jumpers as well, all of which are open by default. The two jumpers located next to the I2C label is for the I²C pull-up resistors. These resistors are not attached by default as there are I²C pull-up resistors on all SparkFun Qwiic slaves. If you're using a 3^rd party board, you may need to close these jumper by the Qwiic connector to attach the pull-ups to the I²C bus. The jumper by the USB-C connector is for bypassing the 0.5A PTC fuse. This is for special cases where you need a lot current. Most of the time, you can leave this jumper open.

Dimensions

The RED-V RedBoard uses the Arduino Uno footprint. There are four mounting holes on the board.

Hardware Hookup

For the scope of the tutorial, you'll use a USB C cable to power, upload code, and send serial to the board. Simply connect the computer's USB port and the RED-V. The board uses standard Arduino Uno R3 footprint with female headers to stack Arduino shields and easily connect prototyped circuits on breadboards with jumper wires.

Software Development Guide

There are a few environments to get started with the RED-V. For information about programming the RED-V RedBoard, check out the following tutorial.

Resources and Going Further

Now that you've successfully got started with your RED-V RedBoard, it's time to incorporate it into your own project! For more information, check out the resources below:

• Schematic (PDF)
• Eagle Files (ZIP)
• Dimensions
• Qwiic Landing Page
• RISC-V
  • Specifications
  • Software Status
  • Cores
• SiFive
  • E310-G002
    • Datasheet (PDF)
    • Manual (PDF)
  • Freedom Studio and E SDK
  • Freedom Studio User Manual (PDF)
• GitHub Hardware Repo
• SFE Product Showcase

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

SparkFun Qwiic Button Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1108

Introduction

Buttons are a great way to add a tactile input to your project but dealing with pull-up resistors, debouncing, polling, and using GPIO pins for each button can be a hassle. Enter the Qwiic Button (Red) and the Qwiic Button Breakout! These breakouts eliminate nearly all the inconvenience of using buttons by converting everything to an easy-to-use I²C connection using the Qwiic Interface.

added to your cart!

SparkFun Qwiic Button - Red LED

In stock BOB-15932

The SparkFun Qwiic Button with red LED simplifies all of those nasty worries away into an easy to use I2C device, no solderin…

$7.50

FavoritedFavorite0

Wish List

added to your cart!

SparkFun Qwiic Button Breakout

In stock BOB-15931

The SparkFun Qwiic Button Breakout simplifies all of those nasty worries away into an easy to use I2C device, and with our Qw…

$4.95

FavoritedFavorite0

Wish List

We have two versions of the Qwiic Button available. The Qwiic Button (Red) comes with a pre-populated red pushbutton with a built in LED to illuminate the button and the Qwiic Button Breakout leaves the button unpopulated so you can choose your own color for your tactile button.

Using the Qwiic Button is as simple as sending the command button.isPressed() to check the status of the button. In addition to handling status checks and debouncing, the Qwiic Button has a configurable interrupt pin which can be adjusted to activate upon a button press or click. This allows you to trigger specific behavior or functions in your code when the button is used and frees up processing time that would normally be used to constantly poll a button's state.

The Qwiic Button also includes a First-in First-Out (FIFO Queue) which keeps track of when the button was pressed so if you are hosting a game show you can easily keep track of which contestant pressed their button first without needing to constantly poll the buttons!

Required Materials

The Qwiic Button requires a Qwiic-enabled microcontroller:

SparkFun Thing Plus - ESP32 WROOM

Out of stock WRL-14689

The SparkFun ESP32 Thing Plus is the next step to get started with Espressif IoT ideations while still enjoying all the ameni…

7

FavoritedFavorite17

Wish List

added to your cart!

SparkFun RedBoard Artemis

In stock DEV-15444

The RedBoard Artemis takes the incredibly powerful Artemis module from SparkFun and wraps it up in an easy to use and familia…

$19.95

FavoritedFavorite9

Wish List

added to your cart!

SparkFun RedBoard Qwiic

In stock DEV-15123

The SparkFun RedBoard Qwiic is an Arduino-compatible development board with a built in Qwiic connector, eliminating the need …

$19.95

5

FavoritedFavorite11

Wish List

added to your cart!

SparkFun Qwiic Micro - SAMD21 Development Board

In stock DEV-15423

The SparkFun Qwiic Micro is molded to fit our standard 1" x 1" Qwiic board size which makes it our smallest SAMD21 micro-cont…

$19.95

1

FavoritedFavorite7

Wish List

And you will also need a Qwiic cable:

added to your cart!

Qwiic Cable - 100mm

In stock PRT-14427

This is a 100mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite12

Wish List

added to your cart!

Qwiic Cable - 200mm

Out of stock PRT-14428

This is a 200mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite7

Wish List

added to your cart!

Qwiic Cable - 50mm

In stock PRT-14426

This is a 50mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together …

$0.95

FavoritedFavorite10

Wish List

added to your cart!

Qwiic Cable - 500mm

In stock PRT-14429

This is a 500mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.95

FavoritedFavorite7

Wish List

Or, if you want to use a microcontroller without a Qwiic connector, you can add one using one of our Qwiic Shields, the Qwiic Adapter board, or adapter cables:

added to your cart!

Qwiic Cable - Breadboard Jumper (4-pin)

In stock PRT-14425

This is a jumper adapter cable that comes pre-terminated with a female Qwiic JST connector on one end and a breadboard hookup…

$1.50

FavoritedFavorite14

Wish List

added to your cart!

SparkFun Qwiic Shield for Arduino

In stock DEV-14352

The SparkFun Qwiic Shield is an easy-to-assemble board that provides a simple way to incorporate the Qwiic Connect System wit…

$6.95

FavoritedFavorite21

Wish List

added to your cart!

SparkFun Qwiic Adapter

In stock DEV-14495

The SparkFun Qwiic Adapter provides the perfect means to make any old I²C board into a Qwiic enabled board.

$1.50

FavoritedFavorite14

Wish List

added to your cart!

Qwiic Cable - Female Jumper (4-pin)

In stock CAB-14988

This is a jumper adapter cable that comes pre-terminated with a female Qwiic JST connector on one end and female connectors o…

$1.50

FavoritedFavorite1

Wish List

Finally, if you are using the Qwiic Button Breakout you'll need to solder a button to the board:

added to your cart!

Momentary Pushbutton Switch - 12mm Square

In stock COM-09190

This is a standard 12mm square momentary button. What we really like is the large button head and good tactile feel (it 'clic…

$0.50

4

FavoritedFavorite36

Wish List

added to your cart!

LED Tactile Button- White

In stock COM-10439

This is a simple LED-illuminated tactile button with a clear cap. It's just like a basic tactile button, but it lights up whi…

$2.10

1

FavoritedFavorite11

Wish List

added to your cart!

LED Tactile Button - Green

In stock COM-10440

This is a simple LED-illuminated tactile button with a green cap. It's just like a basic tactile button, but it lights up gre…

$2.10

FavoritedFavorite11

Wish List

added to your cart!

LED Tactile Button - Blue

In stock COM-10443

This is a simple LED-illuminated tactile button with a clear cap. It's just like a basic tactile button, but it lights up blu…

$2.10

FavoritedFavorite18

Wish List

Realistically, you can solder any pushbutton to the Qwiic Button Breakout so long as it fits the button footprint. We have a couple other options available in our Button Category that will work perfectly with the Qwiic Button Breakout.

Additional Tools for Soldering to the Qwiic Button Breakout

Note: If you want to use the Qwiic Button Breakout then you will need to solder a tactile button to the board. You may already have a few of these items, so feel free to modify your cart based on your needs.

added to your cart!

Digital Multimeter - Basic

In stock TOL-12966

The digital multimeter (DMM) is an essential tool in every electronic enthusiasts arsenal. The SparkFun Digital Multimeter, h…

$14.95

20

FavoritedFavorite39

Wish List

added to your cart!

SparkFun Beginner Tool Kit

22 available TOL-14681

This assortment of tools is great for those of you who need a solid set of tools to start your workbench on the right foot!

$54.95

FavoritedFavorite3

Wish List

added to your cart!

Solder Lead Free - 15-gram Tube

In stock TOL-09163

This is your basic tube of unleaded (Pb-free) solder with a no clean, water soluble resin core. 0.031" gauge and 15 grams. …

$3.50

2

FavoritedFavorite9

Wish List

added to your cart!

Soldering Iron - 30W (US, 110V)

In stock TOL-09507

This is a very simple fixed temp, quick heating, 30W 110/120 VAC soldering iron. We really enjoy using the more expensive iro…

$9.95

7

FavoritedFavorite18

Wish List

Suggested Reading

If you aren't familiar with the Qwiic system, we recommend reading here for an overview:

Qwiic Connect System

We would also recommend taking a look at the following tutorials if you aren't familiar with them.

Hardware Overview

Tactile Button

This is a standard pushbutton with a built in red LED. The LED's anode (positive pin) is connected to an I/O pin on the ATtiny84 so you can turn it on and off as well as control the brightness. If you have the Qwiic Button Breakout, you can choose your own color of button from the selection listed in the Introduction of this guide or any tactile button that fits the footprint on the breakout.

Red Tactile Button	Button Footprint

Qwiic and I²C Interface

The easiest way to use the Qwiic Button is with the Qwiic connect system. Simply plug in a Qwiic Cable to start talking to it.

Qwiic Connectors	I2C Pins

Alternatively, you can solder to the I²C pins broken out on the board.

ATtiny84

The ATtiny84 has pre-installed firmware to handle the various functions of the Qwiic Button. It acts as an intermediary device to send and receive I²C data for things like button presses, clicks, the FIFO queue and it allows you to set a custom I²C address for the Qwiic Button.

Jumpers

I²C Address Jumpers

There are four solder jumpers on the board (labeled A0, A1, A2 and A3) you can close to set the I²C address. The firmware reads the logic of each address pin so, by closing multiple jumpers, you can modify the Qwiic Button with up to sixteen unique addresses! If you do not want to use the address pins, the address can also be configured using the ChangeI2CAddress Example from our Arduino Library.

• All Open: Factory or User Set I²C Slave Address: 0x6F (Factory Set) or 0x## (User Set)
• Alternate Address Jumpers: Closing an address jumper sets the pin LOW. On boot-up, the firmware checks the state of these four pins and adjusts the I²C address following this logic: 0b0110,A3,A2,A1,A0 For example, with both A0 and A1 jumpers closed, (A0 = 0, A1 = 0, A2 = 1, A3 = 1) the I²C address of the Qwiic Button is set to 0x6C (0b01101100).

I²C Pull-Up Resistors

Severing the trace on the I²C jumper will remove the 2.2kΩ pull-up resistors from the I²C bus. If you have many devices on your I²C bus you may want to open these jumpers by severing the trace in between the pads.

Interrupt Pin

The Interrupt Pin can be used to trigger events on your microcontroller. It is active LOW and can be configured to activate on either a button press (held down) and click (press-and-release). By default, the Interrupt Pin is pulled to 3.3V via a 10K resistor through this jumper. Just like the I²C pull-up resistors, you can open it by severing the trace in between the pads. This may come in handy for low-power projects that do not require the Interrupt Pin.

Board Dimensions

The breakout board is the standard Qwiic size of 1" x 1" and has two mounting holes that fit a standard 4-40 screw.

Hardware Assembly

With the Qwiic connector system, assembling the hardware is simple. All you need to do is connect your Qwiic Button to Qwiic-enabled microcontroller with a Qwiic cable. Otherwise, you can use the I²C pins if you don't have a Qwiic connector on your microcontroller board. Just be aware of your input voltage and any logic level shifting you may need to do since the Qwiic system runs at 3.3V.

If you have the Qwiic Button Breakout, you will need to solder a button into place. If you are using a Tactile Button with an integrated LED, remember to pay close attention to the polarity marks on your button and match them to the markings on the top of the Qwiic Button Breakout. If you purchased a tactile button from SparkFun, the anode will be marked with a small "+" on the top of the button.

Once your button(s) are soldered into place and you're certain all pins are well connected, you're ready to go! The image below shows two of the several options for buttons on the Qwiic Button. One is the standard Red LED Tactile Button and the other is from our Multicolor Button 4-Pack:

Qwiic Button Arduino Library

The easiest way to install the library is to search for SparkFun Qwiic Button in the Arduino Library Manager tool. You can also manually install the Qwiic Button Library from the GitHub Repository or you can download it by clicking the button below.

Library Functions

Here is a list of the functions of the library with some quick descriptions of what they do. The examples cover most of the functions so we recommend going through them first.

Device Status

• begin(uint8_t address = DEFAULT_ADDRESS, TwoWire &wirePort = Wire);- Sets device I²C address to a user-specified address, over whatever port the user specifies.
• isConnected();- Returns true if the button will acknowledge over I²C, false otherwise.
• uint8_t deviceID();- Return the 8-bit device ID of the attached device.
• checkDeviceID();- Returns true if the device ID matches that of either the button or the switch
• uint8_t getDeviceType();- Returns 1 if a button is attached, 2 if a switch is attached. Returns 0 if there is no device attached.
• uint16_t getFirmwareVersion();- Returns the firmware version of the attached device as a 16-bit integer. The leftmost (high) byte is the major revision. The rightmost (low) byte is the minor version number. (Ex. 0x0202 is v2.02)
• setI2Caddress(uint8_t address);- Configures the attached device to attach to the I²C bus using the specified address.
• uint8_t getI2Caddress();- Returns the I2C address of the device.

Button Status/Configuration

• isPressed();- Returns 1 if the button is pressed, and 0 otherwise.
• hasBeenClicked();- Returns 1 if the button was clicked, and 0 otherwise.
• uint8_t setDebounceTime(uint16_t time);- Sets the time that the button waits for the mechanical contacts to settle (in ms) and checks if the register was set properly. Returns 0 on success, 1 on register I2C write fail, and 2 if the value didn't get written into the register properly.
• uint16_t getDebounceTime();- Returns the value set to wait for the button's the mechanical contacts to settle, (in ms).

Interrupt Status/Configuration

• uint8_t enablePressedInterrupt();- Configure the interrupt pin to go LOW while the button is pressed (held down).
• uint8_t disablePressedInterrupt();- Sets the interrupt to no longer trigger while the button is pressed.
• uint8_t enableClickedInterrupt();- Configure the interrupt pin to go LOW when the button is clicked.
• uint8_t disableClickedInterrupt();- Configures the interrupt pin to no longer go low when the button is clicked.
• uint8_t clearEventBits();- Sets "isPressed", "hasBeenClicked", and "eventAvailable" to zero.
• uint8_t resetInterruptConfig();- Resets all interrupt configuration settings back to defaults.

FIFO Queue

• isPressedQueueFull();- Checks the queue of button press timestamps and returns true if full, false otherwise.
• isPressedQueueEmpty();- Opposite of the above function. Checks if the timestamp queue is empty.
• unsigned long timeSinceLastPress();- Returns the time (in ms) since the last button press.
• unsigned long timeSinceFirstPress();- Returns time (in ms) since the first button press.
• popPressedQueue();- Returns the oldest value in the Pressed Queue (ms since first button press), and then removes it.
• isClickedQueueFull();- Checks the queue of button click timestamps and returns true if full, false otherwise.
• isClickedQueueEmpty();- Opposite of the above function. Checks if the timestamp queue is empty.
• unsigned long timeSinceLastClick();- Returns the time (in ms) since the last button click.
• unsigned long timeSinceFirstClick();- Returns the time (in ms) since the first button click.
• popClickedQueue();- Returns the oldest value in the Clicked Queue (ms since first button click), and then removes it.

Button LED Configuration

• LEDoff();- Turn the button LED off.
• LEDon(uint8_t brightness = 255);- Turn the button LED on and set the brightness.
• LEDconfig(uint8_t brightness, uint16_t cycleTime, uint16_t offTime, uint8_t granularity = 1);- Configures the button LED.
  • Brightness: Stores the brightness of the LED. Accepts values between 0 and 255.
  • cycleTime: Total pulse cycle time (in ms). Does not include off time.
  • offTime: Off time between pulses (in ms). Default is 500 ms.
  • granularity: Amount of steps it takes to get to the set brightness level.

Internal I²C Abstraction

• uint8_t readSingleRegister(Qwiic_Button_Register reg); - Reads a single 8-bit register.
• uint16_t readDoubleRegister(Qwiic_Button_Register reg); - Reads a 16-bit register (little endian).
• unsigned long readQuadRegister(Qwiic_Button_Register reg); - Reads a 32-bit register (little endian).
• writeSingleRegister(Qwiic_Button_Register reg, uint8_t data); - Attempts to write data into a single 8-bit register. Does not check to make sure it was written successfully. Returns 0 if there was no error on I2C transmission, and 1 otherwise.
• writeDoubleRegister(Qwiic_Button_Register reg, uint16_t data); - Attempts to write data into a double (two 8-bit) registers. Does not check to make sure it was written successfully. Returns 0 if there was no error on I2C transmission, and 1 otherwise.
• uint8_t writeSingleRegisterWithReadback(Qwiic_Button_Register reg, uint8_t data); - Writes data into a single 8-bit register, and checks to make sure the data was written successfully. Returns 0 on no error, 1 on I2C write fail, and 2 if the register doesn't read back the same value that was written.
• uint16_t writeDoubleRegisterWithReadback(Qwiic_Button_Register reg, uint16_t data); - Writes data into a double (two 8-bit) registers, and checks to make sure the data was written successfully. Returns 0 on no error, 1 on I2C write fail, and 2 if the register doesn't read back the same value that was written.

Arduino Examples

In this section we will go over a few of the examples from our Qwiic Button Arduino Library. Here is a full list of all the examples included in the library:

• Example 1 - Prints the button status.
• Example 2 - Turns the button LED on while the button is pressed.
• Example 3 - Pulses the button LED while the button is pressed.
• Example 4 - Demonstrates how to use the FIFO Queue and returns time elapsed since button presses.
• Example 5 - Details how to identify and change the I²C address.
• Example 6 - I²C Bus Configuration. Useful for devices with multiple I²C ports.
• Example 7 - Sets up 2 Qwiic Buttons and reads their statuses.
• Example 8 - Configures the button to toggle the interrupt pin when pressed.

Example 1: Print Button Status

The code for Example1_PrintButtonStatus connects the Qwiic Button to the I²C bus and prints the status of the button (pressed or not pressed) to the Serial Monitor.

Example 3 Pulse When Pressed

Example3_PulseWhenPressed connects the Qwiic Button to the I²C bus and runs the Button LED through a configured sequence when the button is pressed. The code configures the LED settings for brightness, cycleTime and offTime to pulse the Button LED while it is pressed. Try playing around with these settings to change the behavior of the LED.

Example 4 Queue Usage

Example4_QueueUsage demonstrates how to call, check, and alter the FIFO Queue for a button press and button click. The code will check both the Pressed and Clicked queues and, if the queue is not empty, prints over serial the time since the first press (since the queue was last cleared) and the time since the last press. Entering "P" in the serial monitor will "pop" the Pressed Queue to return the oldest value stored in the queue and then remove it. Entering "C" will perform the same action for the Clicked Queue.

Example 5 Change I²C Address

Example5_ChangeI2CAddress checks to initialize the Qwiic Button on the I²C bus. If the device ID matches what is expected (0x6F by default), it then will print some helpful information for changing the I²C address and prompt you for an input to change the address. Once a new device ID is input and is valid, the code writes the new I²C address to EEPROM on the ATtiny84 and prints out a success note along with the new device ID. If the entered address is invalid or for some reason the write fails, the code will print out an error detailing what failed.

If the device ID does not match what is expected, it runs a scan for devices on the bus and prints out the ID of any attached device. Make sure to set up the Serial Monitor for the correct baud rate and enable both Newline and Carriage Return. Also, do not enter the "0x" prefix. For example, you want to set the address to "0x5B", type in "5B" and press enter. The gif below shows the serial printout of a successful initialization and device address change to 0x5B:

Example 8 External Interrupt

Example8_ExtInterrupt demonstrates how to use the external interrupt pin to trigger an event on an attached microcontroller. You will want to solder to the INT pin and connect it to an interrupt-capable pin. If you just need to quickly prototype a circuit using the INT pin on the Qwiic Button, you can connect to it using something like these IC Hooks. The photo below demonstrates how to use the IC Hook for a temporary connection.

The code initializes the Qwiic Button on the I²C bus, attaches an interrupt to the selected pin (D2 by default), and configures the interrupt function for any button event (pressed or clicked). The INT pin will go LOW whenever a button event is registered and the selected interrupt pin on the microcontroller will fire whenever it sees a FALLING edge (going from HIGH to LOW). If you want to see it in action, you could attach an LED to the selected interrupt pin or you can modify the code to toggle all sorts of functions whenever the interrupt pin goes LOW.

Register Map

If you would like to use a different development environment than Arduino, you can use the register map below to communicate with the Qwiic Button.

The Qwiic Button behaves as a normal I²C slave. First write the address of the register you would like to read or write, then follow that I²C command with a Read to read the given register or a Write and a data byte to write to a register.

Resources and Going Further

For more information, check out the resources below:

• Schematic (PDF)
• Eagle Files (ZIP)
• Board Dimensions (PNG)
• Qwiic Button Arduino Library
• GitHub Hardware Repo

Need help getting started with Arduino and I²C? Check out these resources:

• Arduino I²C Scanner Example
• Arduino Wire Library Reference Page
• Arduino Wire Library (In-Depth) Reference

Looking for some inspiration for a project using the Qwiic Button? Check out this GPS Geo-Mapping project by Brandon J. Williams.

Before you go, here are some other tutorials using the Qwiic Connect System you may want to look through:

learn.sparkfun.com | CC BY-SA 3.0 | SparkFun Electronics | Niwot, Colorado

SparkFun Qwiic Shield for Arduino Nano Hookup Guide a learn.sparkfun.com tutorial

Available online at: http://sfe.io/t1106

Introduction

The SparkFun Qwiic Shield for Arduino Nano allows you to add the SparkFun Qwiic ecosystem to development boards that use the Arduino Nano Footprint in an easy-to-assemble shield. It connects the I²C bus (GND, 3.3V, SDA, and SCL) on your Arduino Nano to four SparkFun Qwiic connectors. The Qwiic ecosystem allows for easy daisy chaining so, as long as your devices are on different addresses, you can connect as many Qwiic devices as you'd like.

added to your cart!

SparkFun Qwiic Shield for Arduino Nano

In stock DEV-16130

The SparkFun Qwiic Shield for Arduino Nano makes it so you can use SparkFun's Qwiic connect ecosystem with development boards…

$3.50

FavoritedFavorite0

Wish List

Required Materials

To follow along with this guide, you will need an Arduino with the Nano footprint. This includes the all variants of the Arduino Nano and many other Arduino Nano-compatible boards! Here are just a few of the compatible boards.

Arduino Nano 33 BLE Sense

Out of stock DEV-15580

Small, powerful, BT connected and with all the sensors you may need to design innovative applications. This compact and re…

FavoritedFavorite0

Wish List

added to your cart!

Arduino Nano 33 BLE

In stock DEV-15588

Designed for short range BT interactions and power savvy projects. This compact and reliable NANO board is built around th…

$24.95

FavoritedFavorite1

Wish List

added to your cart!

Arduino Nano 33 IoT with Headers

In stock DEV-15589

The ease of use of a Nano board with the addition of secure IoT and BT connectivity. This small, robust and powerful board…

$25.95

FavoritedFavorite2

Wish List

added to your cart!

Arduino Nano Every

In stock DEV-15590

Turn your ideas into a reality quickly with the new Arduino Nano Every This small, robust and powerful board has the same …

$14.95

FavoritedFavorite2

Wish List

You will also need some headers to solder to both your Arduino Nano and Qwiic Shield:

added to your cart!

Break Away Headers - Straight

In stock PRT-00116

A row of headers - break to fit. 40 pins that can be cut to any size. Used with custom PCBs or general custom headers.

$1.50

20

FavoritedFavorite100

Wish List

added to your cart!

Female Headers

In stock PRT-00115

Single row of 40-holes, female header. Can be cut to size with a pair of wire-cutters. Standard .1" spacing. We use them exte…

$1.50

7

FavoritedFavorite54

Wish List

added to your cart!

Break Away Headers - Long

In stock PRT-10158

These are a longer version of our [standard](http://www.sparkfun.com/commerce/product_info.php?products_id=116) break away he…

$2.95

3

FavoritedFavorite12

Wish List

Now you probably would not want the Qwiic Shield for Arudino Nano if you didn't have any Qwiic products to use with it, right? Well, if you don't have any Qwiic products, the following might not be a bad place to start.

added to your cart!

SparkFun GPS Breakout - NEO-M9N, U.FL (Qwiic)

Out of stock GPS-15712

The SparkFun NEO-M9N GPS Breakout is a high quality, GPS board with equally impressive configuration options.

$64.95

2

FavoritedFavorite4

Wish List

added to your cart!

SparkFun High Precision Temperature Sensor - TMP117 (Qwiic)

In stock SEN-15805

The SparkFun Qwiic TMP117 Breakout is a high precision temperature sensor equipped with an I2C interface.

$13.95

1

FavoritedFavorite8

Wish List

added to your cart!

SparkFun Qwiic Motor Driver

In stock ROB-15451

The SparkFun Qwiic Motor Driver takes all the features of the Serial Controlled Motor Driver and miniaturizes them, adding Qw…

$14.95

1

FavoritedFavorite3

Wish List

added to your cart!

SparkFun Qwiic Keypad - 12 Button

23 available COM-15290

The SparkFun Qwiic Keypad comes fully assembled and makes the development process for adding a 12 button keypad easy.

$9.95

3

FavoritedFavorite11

Wish List

You will need some of our Qwiic cables to connect your devices to the shield. Below are a few options:

added to your cart!

Qwiic Cable - 100mm

In stock PRT-14427

This is a 100mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite14

Wish List

added to your cart!

Qwiic Cable - 200mm

Out of stock PRT-14428

This is a 200mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.50

FavoritedFavorite8

Wish List

added to your cart!

Qwiic Cable - 50mm

In stock PRT-14426

This is a 50mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together …

$0.95

FavoritedFavorite11

Wish List

added to your cart!

Qwiic Cable - 500mm

In stock PRT-14429

This is a 500mm long 4-conductor cable with 1mm JST termination. It’s designed to connect Qwiic enabled components together…

$1.95

FavoritedFavorite8

Wish List

Lastly, if you want to use a non-Qwiic I²C device, these adapters help to convert it to a Qwiic connector:

added to your cart!

Qwiic Cable - Breadboard Jumper (4-pin)

In stock PRT-14425

This is a jumper adapter cable that comes pre-terminated with a female Qwiic JST connector on one end and a breadboard hookup…

$1.50

FavoritedFavorite15

Wish List

added to your cart!

SparkFun Qwiic Adapter

In stock DEV-14495

The SparkFun Qwiic Adapter provides the perfect means to make any old I²C board into a Qwiic enabled board.

$1.50

FavoritedFavorite15

Wish List

added to your cart!

Qwiic Cable - Female Jumper (4-pin)

In stock CAB-14988

This is a jumper adapter cable that comes pre-terminated with a female Qwiic JST connector on one end and female connectors o…

$1.50

FavoritedFavorite2

Wish List

Required Tools

You will need a soldering iron, solder, and general soldering accessories to solder the header pins to the Qwiic shields.

added to your cart!

Solder Lead Free - 15-gram Tube

In stock TOL-09163

This is your basic tube of unleaded (Pb-free) solder with a no clean, water soluble resin core. 0.031" gauge and 15 grams. …

$3.50

2

FavoritedFavorite9

Wish List

added to your cart!

Soldering Iron - 30W (US, 110V)

In stock TOL-09507

This is a very simple fixed temp, quick heating, 30W 110/120 VAC soldering iron. We really enjoy using the more expensive iro…

$9.95

7

FavoritedFavorite18

Wish List

Suggested Reading

If you aren't familiar with the Qwiic ecosystem, we recommend reading here for an overview:

Qwiic Connect System

We would also recommend taking a look at the following tutorials if you aren't familiar with them: