Merge branch 'develop'

docs/DigitalIn.rst

@@ -11,7 +11,8 @@ The ``mode`` specifies the behavior of the component attached to the pin:
 
 - in ``DIRECT`` mode (default) the unit will be "on" when the voltage on the pin is high (Vref, typically 5V)
 - in ``INVERTED`` mode the unit will be "on" when the voltage on the pin is low (GND)
-- in ``INTERNAL_PULLUP`` mode the internal 20K pullup resistor is used, which simplifies the use of switches and buttons
+- in ``INTERNAL_PULLUP`` mode the internal `pullup resistor <https://en.wikipedia.org/wiki/Pull-up_resistor>`_ is used,
+  simplifying usage of switches and buttons
 
 Debouncing
 ----------
@@ -30,7 +31,8 @@ of the `Bounce2 Arduino Library <https://github.com/thomasfredericks/Bounce2>`_.
 ---------
 
 Turns on and off a light emitting diode (LED) connected to digital pin 13, when
-pressing a pushbutton attached to digital pin 2.
+pressing a pushbutton attached to digital pin 2. Pushbutton should be wired by connecting
+one side to pin 2 and the other to ground.
 
 .. code-block:: c++
 

docs/array.rst

@@ -0,0 +1,62 @@
+.. include:: defs.hrst
+
+[] (arrays)
+===========
+
+An array is a collection of variables or objects that are accessed with an index number. 
+Arrays can be complicated, but using simple arrays is relatively straightforward.
+
+For a general description of arrays, please refer to `this page <https://www.arduino.cc/reference/en/language/variables/data-types/array/>`_.
+
+Arrays of Plaquette units such as :doc:`DigitalIn`. :doc:`SineOsc`, and :doc:`MinMaxScaler` can be easily created using the following syntax:
+
+.. code-block:: c++
+
+    UnitType array[] = { UnitType(...), UnitType(...), ... };
+
+For example, the following code will create an array of three (3) digital outputs on pins 10, 11, and 12:
+
+.. code-block:: c++
+
+    DigitalOut leds[] = { DigitalOut(10), DigitalOut(11), DigitalOut(12) };
+
+When initializing a unit with a single parameter, one can simply use the value of the parameter at creation time. Hence the previous code could
+be rewritten as:
+
+.. code-block:: c++
+
+    DigitalOut leds[] = { 10, 11, 12 };
+
+When more than a single parameter is used, however, it needs to be called explicitely with the unit name:
+
+.. code-block:: c++
+
+    SquareOsc oscillators[] = { 1.0, 2.0, SquareOsc(3.0, 0.8) };
+
+.. warning::
+
+    Units in array need to be all of the same type. In other words, it is not currently possible to mix different types of objects such as 
+    DigitalIn and SquareOsc in the same array.
+
+
+|Example|
+---------
+
+.. code-block:: c++
+
+  #include <Plaquette.h>
+
+  AnalogOut leds[] = { 9, 10, 11 };
+
+  // Creates three triangle oscillators with a 2 seconds period, with different width.
+  TriOsc oscillators[] = { TriOsc(2.0, 0.0), 2.0, TriOsc(2.0, 1.0) };
+
+  void begin() {}
+
+  void step() {
+    // Send each oscillator to its corresponding LED.
+    for (int i=0; i<3; i++) {
+      oscillators[i] >> leds[i];
+    }
+  }
+

docs/conf.py

@@ -44,8 +44,8 @@
 project = u'Plaquette'
 copyright = u'2015-2023, Plaquette'
 author = u'Sofian Audry & Thomas O. Fredericks'
-version = '0.4.5'
-release = '0.4.5'
+version = '0.5.0'
+release = '0.5.0'
 language = 'en'
 exclude_patterns = ['_build']
 pygments_style = 'sphinx'

docs/features.rst

@@ -126,7 +126,7 @@ Plaquette forbids the use of blocking functions such as Arduino's
 Rather, it invites programmers to adopt a frame-by-frame approach to coding similar
 to `Processing <https://processing.org/>`_.
 
-Compare this (albeit naive) attempt to make an `LED blink <https://www.arduino.cc/en/Tutorial/BuiltInExamples/Blink>`_
+Compare the following attempt to make an `LED blink <https://www.arduino.cc/en/Tutorial/BuiltInExamples/Blink>`_
 when pressing a button in Arduino, versus Plaquette's real-time approach:
 
 +------------------------------------------------+------------------------------------------------+
@@ -138,13 +138,13 @@ when pressing a button in Arduino, versus Plaquette's real-time approach:
 |   int ledPin = 12;                             |     DigitalOut led(12);                        |
 |                                                |                                                |
 |   void setup() {                               |     // Square wave 1 second period.            |
-|     pinMode(buttonPin, INPUT_PULLUP);          |     SquareOsc oscillator(1.0);                 |
+|     pinMode(buttonPin, OUTPUT);                |     SquareOsc oscillator(1.0);                 |
 |     pinMode(ledPin, OUTPUT);                   |                                                |
 |   }                                            |     void begin() {}                            |
 |                                                |                                                |
 |   void loop() {                                |     void step() {                              |
 |     // Button is checked once per second.      |       // Button is checked at all time.        |
-|     if (digitalRead(buttonPin) == LOW) {       |       if (button)                              |
+|     if (digitalRead(buttonPin) == HIGH) {      |       if (button)                              |
 |       digitalWrite(ledPin, HIGH);              |         oscillator >> led;                     |
 |       delay(500); // do nothing for 500ms      |     }                                          |
 |       digitalWrite(ledPin, LOW);               |                                                |

docs/getting_started.rst

@@ -174,11 +174,12 @@ You can also try to add a second parameter to  the constructor to control
 the oscillator's `duty -ycle <https://en.wikipedia.org/wiki/Duty_cycle>`__. 
 
 
-For a fixed period, try changing the dutyCycle to different percentages between 0.0 and 1.0.
-Example:
- - ``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%
+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
 ~~~~~~~~~~~~~~~~~~~~~~

docs/structure.rst

@@ -8,5 +8,6 @@ Core structural functions and operators.
 
    begin
    step
+   array
    dot
    pipe

examples/01.Basics/Blink/Blink.ino

@@ -1,5 +1,5 @@
 /**
- * BlinkOsc
+ * Blink
  *
  * Turns on and off a light emitting diode (LED) connected to a digital
  * pin using a SquareOsc.

examples/02.Digital/BlinkAlarm/BlinkAlarm.ino

@@ -18,20 +18,20 @@
 DigitalOut led(LED_BUILTIN);
 
 // The timer.
-Alarm alarm(1.0); // period: 1 second
+Alarm toggleAlarm(1.0); // period: 1 second
 
 void begin() {
   // Start timer.
-  alarm.start();
+  toggleAlarm.start();
 }
 
 void step() {
   // Every time the metronome "fires": change LED state.
-  if (alarm) {
+  if (toggleAlarm) {
     // Flip LED state.
     led.toggle();
 
     // Restart timer.
-    alarm.start();
+    toggleAlarm.start();
   }
 }

examples/04.Generators/BlinkModulation/BlinkModulation.ino

@@ -0,0 +1,32 @@
+/**
+ * Modulation
+ *
+ * Uses a low-frequency oscillator (LFO) to control the frequency of another
+ * oscillator.
+ * Sends values to the serial output: best visualized using the Arduino Serial Plotter.
+ *
+ * Created in 2019 by Sofian Audry
+ *
+ * This example code is in the public domain.
+ */
+
+#include <Plaquette.h>
+
+// The main oscillator.
+SquareOsc osc;
+
+// The LFO.
+SineOsc lfo(20.0); // 20 seconds period
+
+// The LED.
+DigitalOut led(LED_BUILTIN);
+
+void begin() {}
+
+void step() {
+  // Modulate oscillator BPM between 30 to 180.
+  osc.bpm( lfo.mapTo(30, 180) );
+
+  // Send to LED.
+  osc >> led;
+}

examples/04.Generators/Modulation/Modulation.ino

@@ -25,6 +25,8 @@ void begin() {}
 
 void step() {
   // Modulate oscillator frequency between 1 to 20 Hz.
-  osc.frequency( mapFrom01(lfo, 1, 20) );
+  osc.frequency( lfo.mapTo(1, 20) );
+
+  // Send to serial output.
   osc >> out;
 }

examples/05.Timing/Alarm/Alarm.ino

@@ -19,32 +19,32 @@
 DigitalOut led(LED_BUILTIN);
 
 // The alarm.
-Alarm alarm(1.0); // starting duration: 1 second
+Alarm ledAlarm(1.0); // starting duration: 1 second
 
 // Keeps track of increasing duration of LED.
 float ledDuration;
 
 void begin() {
   // Initialize ledDuration to starting timer duration.
-  ledDuration = alarm.duration();
+  ledDuration = ledAlarm.duration();
 
   // Start timer.
-  alarm.start();
+  ledAlarm.start();
 }
 
 void step() {
   // If timer has reached its duration, perform some actions.
-  if (alarm) {
+  if (ledAlarm) {
     // Switch LED.
     led.toggle();
 
     // If LED is "on" keep it on for a certain time.
     if (led) {
       ledDuration += 0.5;
-      alarm.start(ledDuration);
+      ledAlarm.start(ledDuration);
     }
     // Otherwise keep it off for half a second.
     else
-      alarm.start(0.5);
+      ledAlarm.start(0.5);
   }
 }

examples/05.Timing/Metronome/Metronome.ino

@@ -22,9 +22,9 @@ DigitalOut led(LED_BUILTIN);
 AnalogIn pot(A0);
 
 // The metronome object.
-Metro metronome(1.0);
+Metro metronome; // default period: 1 second
 
-// An alarm object (to make sure the LED light stays visible for a short time).
+// An alarm object (to make sure the LED light stays visible for a short time of 5ms).
 Alarm ledOnAlarm(0.05);
 
 void begin() {
@@ -33,8 +33,8 @@ void begin() {
 }
 
 void step() {
-  // Adjust metronome period with potentiometer from 100ms to 2 seconds.
-  metronome.period(pot.mapTo(0.1, 2.0));
+  // Adjust metronome period with potentiometer from 40 to 200 bpm.
+  metronome.bpm(pot.mapTo(40, 200));
 
   // When the metronome "hits": switch LED on and start timer.
   if (metronome) {

examples/07.Advanced/ArrayBlink/ArrayBlink.ino

@@ -0,0 +1,41 @@
+/**
+ * ArrayBlink
+ *
+ * Demonstrates the use of arrays to turn multiple LEDs on and off according
+ * to different square oscillators.
+ *
+ * The circuit:
+ * - Three LEDs.
+ * - The anode of the LEDs are connected in series with a 220-ohm resistor to pins 4, 5, and 6. 
+ * - Their cathodes connect to ground.
+ * 
+ * Created in 2024 by Sofian Audry
+ *
+ * This example code is in the public domain.
+ */
+#include <Plaquette.h>
+
+// The LED.
+const int N_LEDS = 3;
+
+// A square-wave (on/off) oscillator for each LED.
+// - The first LED will blink once per second.
+// - The second LED will blink once every two seconds with a duty-cycle of 80%.
+// - The third LED will blink once every three seconds.
+SquareOsc oscillators[] = {
+  SquareOsc(1.0), 
+  SquareOsc(2.0, 0.8), 
+  3.0 // shorthand for SquareOsc(3.0)
+};
+
+// The three LEDs.
+DigitalOut leds[] = { 4, 5, 6 }; // shorthand for DigitalOut leds[] = { DigitalOut(4), DigitalOut(5), DigitalOut(6) };
+
+void begin() {}
+
+void step() {
+  // Send oscillator value to corresponding LED.
+  for (int i=0; i<N_LEDS; i++) {
+    oscillators[i] >> leds[i];
+  }
+}

examples/07.Advanced/ArrayMeter/ArrayMeter.ino

@@ -0,0 +1,39 @@
+/**
+ * ArrayBlink
+ *
+ * Demonstrates the use of arrays to create a VU-meter with 5 LEDs.
+ *
+ * The circuit:
+ * - Five LEDs.
+ * - The anode of the LEDs are connected in series with a 220-ohm resistor to pins 4 to 8.
+ * - Their cathodes connect to ground.
+ * 
+ * Created in 2024 by Sofian Audry
+ *
+ * This example code is in the public domain.
+ */
+#include <Plaquette.h>
+
+// The LED.
+const int N_LEDS = 5;
+
+// An analog sensor such as a microphone or photocell.
+AnalogIn sensor(A0);
+
+// The three LEDs.
+DigitalOut leds[] = { 4, 5, 6, 7, 8 }; // shorthand for DigitalOut leds[] = { DigitalOut(4), DigitalOut(5), DigitalOut(6), ... };
+
+void begin() {}
+
+void step() {
+  // Map sensor value to number of LEDs to turn on.
+  // NOTE: Due to the cast to int, the sensor value will need to be 1.0 (100%) to turn on all LEDs. 
+  // This can be adjusted to be more tolerant by changing the call to mapFrom01(sensor, 0, N_LEDS+1).
+  int nLedsOn = (int)mapFrom01(sensor, 0, N_LEDS);
+
+  // Light up LEDs.
+  for (int i=0; i<N_LEDS; i++) {
+    // Turn on LED if i < nLedsOn.
+    (i < nLedsOn) >> leds[i];
+  }
+}

library.properties

@@ -1,5 +1,5 @@
 name=Plaquette
-version=0.4.5
+version=0.5.0
 author=Sofian Audry & Thomas Ouellet Fredericks
 maintainer=Sofian Audry & Thomas Ouellet Fredericks
 sentence=An object-oriented library for creative physical computing.