Getting started

This short introduction will guide you through the first steps of using Plaquette.

We also recommend watching our introductory video tutorial series.

Introduction to Plaquette video tutorial series

Step 1: Install Plaquette

If you do not have Arduino installed on your machine you need to download and install the Arduino IDE for your platform.

Once Arduino is installed, please install Plaquette as an Arduino library following these instructions.

Step 2: Your first Plaquette program

We will begin by creating a simple program that will make the built-in LED on your microcontroller blink.

Create a new sketch

Create a new empty sketch by selecting File > New.

IMPORTANT: New Arduino sketches are initialized with some “slug” starting code. Make sure to erase the content of the sketch before beginning. You can use Edit > Select All and then click Del or Backspace.

Include library

Include the Plaquette library by typing:

#include <Plaquette.h>

Create an output unit

Now, we will create a new unit that will allow us to control the built-in LED:

DigitalOut myLed(13);

In this statement, DigitalOut is the type of unit that we are creating. There also exists other types of units, which will be described later. DigitalOut is a type of software unit that can represent one of the many hardware pins for digital output on the Arduino board. One way to think about this is that the DigitalOut is a “virtual” version of the Arduino pin. These can be set to one of two states: (“on/off”, “high/low”, “1/0”).

The word myLed is a name for the object we are creating.

Finally, 13 is a parameter of the object myLed that specifies the hardware pin that it corresponds to on the board. In English, the statement would thus read as: “Create a unit named``myLed`` of type DigitalOut on pin 13.”

Note

Most Arduino boards have a pin connected to an on-board LED in series with a resistor and on most boards, this LED is connected to digital pin 13. The constant LED_BUILTIN is the number of the pin to which the on-board LED is connected.

Create an input unit

We will now create another unit that will generate a signal which will be sent to the LED to make it blink. To this effect, we will use the SquareOsc unit type which generates a square wave oscillating between “on/high/one” and “off/low/zero” at a regular period of 2.0 seconds:

SquareOsc myOsc(2.0);

Create the begin() function

Each Plaquette sketch necessitates the declaration of two functions: begin() and step().

Function begin() is called only once at the beginning of the sketch (just like the setup() function in Arduino). For our first program, we do not need to perform any special configuration at startup so we will leave the begin() function empty:

void begin() {}

Create the step() function

The step() function is called repetitively and indefinitely during the course of the program (like the loop() function in Arduino).

Here, we will send the signal generated by the myOsc input unit to the myLed output unit. We will do this by using Plaquette’s special >> operator:

void step() {
  myOsc >> myLed;
}

In plain English, the statement myOsc >> myLed reads as: “Take the value generated by myOsc and put it in myLed.”

Upload sketch

Upload your sketch to the Arduino board. You should see the LED on the board blinking once every two seconds at a regular pace.

Et voilà!

Full code

#include <Plaquette.h>

DigitalOut myLed(13);

SquareOsc myOsc(2.0);

void begin() {}

void step() {
  myOsc >> myLed;
}

Step 3 : Experiment!

Period and duty cycle

The SquareOsc unit type provides two parameters to configure the oscillator’s behavior:

SquareOsc myOsc(period, dutyCycle);

period can be any positive number representing the period of oscillation (in seconds)
dutyCycle can be any number between 0.0 (0%) and 1.0 (100%), and represents the proportion of the period during which the signal is “high” (ie. “on duty”) (default: 0.5)

Try changing the first parameter in the square oscillator unit to change the period of oscillation. What happens?

You can also try to add a second parameter to the constructor to control the oscillator’s duty -ycle.

For a fixed period, try changing the duty cycle to different percentages between 0.0 and 1.0. Examples:

SquareOsc myOsc(2.0, 0.5); for a duty-cycle of 50% (default)
SquareOsc myOsc(2.0, 0.25); for a duty-cycle of 25%
SquareOsc myOsc(2.0, 0.75); for a duty-cycle of 75%

Adding and multiplying

Add another oscillator with a different period and duty cycle: multiply their values and send the result to the LED.

SquareOsc myOsc2(period, dutyCycle);
// ...
void step() {
  (myOsc * myOsc2) >> myLed;
}

Try adding their values instead: what do you see?

Use a conditional

Add a third oscillator that will “switch” between the two oscillators every 5 seconds using an if…else statement.

// TIP: omitting the duty-cycle parameter results in default value (0.5)
SquareOsc mySwitcher(5.0);
// ...
void step() {
  if (mySwitcher)
    myOsc >> myLed;
  else
    myOsc2 >> myLed;
}

ADVANCED: You can rewrite this expression in a more compact way using the ? : conditional operator:

void step() {
  (mySwitcher ? myOsc : myOsc2) >> myLed;
}

More examples

You will find more examples in File > Examples > Plaquette including:

Using a button
Using an analog input such as a photocell or potentiometer
Using an analog output
Basic filtering (smoothing, re-scaling)
Serial input and output

We also recommend watching our introductory video tutorial series.