Skip to content

Commit

Permalink
Added Timer object and some general cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
@robertgallup
robertgallup committed Jan 12, 2022
1 parent fa873ea commit 74c64bb
Show file tree
Hide file tree
Showing 20 changed files with 346 additions and 314 deletions.
2 changes: 1 addition & 1 deletion LICENSE.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
The MIT License (MIT)

Copyright (c) 2015 Robert Gallup
Copyright (c) 2015-2022 Robert Gallup

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
166 changes: 112 additions & 54 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,60 @@
# BobaBlox Library Documentation

Version: 2.0
Author: Robert Gallup
Date: 7/19/2015
**Version: 2.1.0**
**Author: Robert Gallup**
**Date: 1/11/2022**

BobaBlox is an Arduino library that makes it easier to sketch code for basic hardware components. I've found that in teaching introductory Arduino workshops, that the repetitiveness of typing numerous commands just to make an LED blink can get in the way of learning overall programming concepts. So, I developed BobaBlox. It was initially designed to work with the Adafruit Trinket, but works equally well on standard Arduino models.

Here's an example of using BobaBlox in the standard blink example. First, standard blink:

- - -
# BobaBlox Overview

BobaBlox is an Arduino library that makes it easier to sketch code for basic hardware components. I've found while teaching Arduino workshops, the repetitiveness of typing multiple commands just to make an LED blink can get in the way of learning overall programming concepts. So, I developed BobaBlox. It should work with all standard Arduino boards, including variants such as the Adafruit Trinket.

Here's an example using BobaBlox in the standard blink example. First, standard blink from Arduino examples:

void setup() {
pinMode (13, OUTPUT);
pinMode (13, OUTPUT); // Define pin 13 as an output pin
}

void loop() {
digitalWrite (13, HIGH);
delay (500);
digitalWrite (13, LOW);
delay (500);
digitalWrite (13, HIGH); // Turn the LED on
delay (500); // Delay for 500 milliseconds
digitalWrite (13, LOW); // Turn the LED off
delay (500); // Delay for 500 milliseconds
}

When this is written using BobaBlox, it becomes:

#include <BobaBlox.h>
LED light(13);

void loop () {
light.blink();
}
When this is written using BobaBlox, it becomes:

In this case, setup() isn't required (though it has to be placed in the code). In addition, there are different versions of the blink method for changing the pin, number of blinks, the on-time, and off-time.
#include <BobaBlox.h> // Include the BobaBlox library

LED light(13); // Define the LED on pin 13
void setup() {} // No extra setup statements required
void loop () {
light.blink(); // Each time through the loop, blink the LED on/off
}

The same holds true for the other elements in BobaBlox: Button, Knob, Photocell, and Speaker. In addition to the list, below, documentation for methods implemented for each element is in the associated example application when the library is installed.
Notice that there's no need to type digitalWrite/Delay twice. Also, setup() is empty. The only statement needed, is a "blink" command in loop().

In addition to the documentation, below, see the example BobaBlox sketches when the library is installed.
The same pattern holds true for the other elements in BobaBlox: Button, Knob, Photocell, Speaker and Timer. You can find out more in the following documentation. Also, see the example BobaBlox sketches for working samples.

## Installation
##Installation

The library is installed like other Arduino libraries. You can download a zip of the library and install it using Sketch > Include Library > Add .ZIP Library ... . BobaBlox should also be available in the Arduino Library Manager. Install using the Library Manger by choosing: Sketch > Include Library > Manage Libraries ... . Then, search for and select BobaBlox.


- - -
# BobaBlox Object Reference

## LED

LED's are connected between an Arduino pin and ground, typically with a resistor in series.

#### Declaration

LED led_name(pin);

*led_name* is the name of the LED variable being declared.
*pin* is the number of the pin being used for the LED.

Expand All @@ -54,96 +63,108 @@ LED's are connected between an Arduino pin and ground, typically with a resistor
void on (); // Turns the LED off
void off (); // Turns the LED on
void set (state); // Sets LED on if state is greater than zero
void blink (); // Blinks LED once with default 250ms on and off
void blink (n); // Blinks n times with default blink delay
void blink (n, delay); // Blinks n times with specific delay
void blink (n, delayON, delayOFF); // Blinks n times with delayON and delayOFF
void setBrightness (brightness); // On a PWM pin, sets LED brightness (0-255)

void toggle(); // Toggles the LED on and off
void blink (); // Blinks LED once with default 250ms on and off
void blink (n); // Blinks n times with default blink delay
void blink (n, delay); // Blinks n times with specific delay
void blink (n, delayON, delayOFF); // Blinks n times with delayON and delayOFF
void setBrightness (brightness); // On a PWM pin, sets LED brightness (0-255)

- - -
## Button

Buttons are connected between a pin and ground. The internal pullup resistor is used, so no other external components are required.
Buttons are connected between a pin and ground. The internal pull-up resistor is used, so no other external components are required.

#### Declaration

Button button_name(pin);

*button_name* is name of the button variable being declared.
*pin* is the number of the pin being used for the button. Its mode will be set to *input_pullup*.

#### Methods

int state () // Returns 0 for up, 1 for down
boolean isDown () // Returns true is button is down, false otherwise
boolean isUp () // Returns true if button is up, false otherwise
boolean wasPressed () // Returns true when a button is pressed
boolean wasReleased () // Returns true when a button is released
int state () // Returns 0 for up, 1 for down
boolean isDown () // Returns true is button is down, false otherwise
boolean isUp () // Returns true if button is up, false otherwise
boolean wasPressed () // Returns true when a button is pressed
boolean wasReleased () // Returns true when a button is released


***Notes:***

The Button methods use basic debouncing, but may have difficulties with "noisy" buttons. Also, *wasPressed()* and *wasReleased()* are more responsive the more frequently they are called. In a simple loop without a lot of *delay()* calls, it should be reasonably responsive.



- - -
## Knob

Knobs are potentiometers. This element assumes that the "outside" leads of the Knob are connected to *ground* and *VCC*, respectively. The center lead is connected to an Analog Input pin.
Knobs are potentiometers. This element assumes that the "outside" leads of the Knob are connected to *ground* and *V+*, respectively. The center lead is connected to an analog Input pin.

#### Declaration

Knob knob_name(pin);

*knob_name* is name of the knob variable being declared.
*pin* is the number of the pin being used to connect the Knob.
*pin* is the number of the analog pin being used to connect to the center lead of the Knob.

#### Methods

int value (); // Returns the current value (0-1023)
int value (int rangeStart, int rangeEnd) // Returns value mapped to specified range
int value (); // Returns the current value (0-1023)
int value (int rangeStart, int rangeEnd) // Returns value mapped to specified range

***Notes:***

Potentiometers return values from 0 to 1023 on the 10-bit Arduino ADC. However, the range for setting the brightness of an LED, for example, is 0-255. Often, this is change in range is accomplished by using the *map()* function. However *map()* can be a bit complicated to understand. The version of *value()* that allows you to specify the range to return does the mapping automatically and is more straightforward.
Potentiometers return values from 0 to 1023 on the 10-bit Arduino analog to digital convertor (ADC). However, the range for setting the brightness of an LED, for example, is 0-255. Often, this is change in range is accomplished by using the *map()* function. However *map()* can be a bit complicated to understand. The version of *value()* that allows you to specify the range, does the mapping automatically and is more straightforward.



- - -
## Photocell

Photocells are identical to Knobs in implementation. This element assumes that the one lead from the photocell is connected to *VCC*. The other lead is connected to *ground* through a series resistor. The point where the photocell and series resistor are joined is connected to an Analog Input pin.
Photocells are identical to Knobs in implementation. This element assumes that the one lead from the photocell is connected to *V+*. The other lead is connected to *ground* through a series resistor. The point where the photocell and series resistor are joined is connected to an Analog Input pin.

#### Declaration

Photocell photocell_name(pin);

*photocell_name* is name of the Photocell variable being declared.
*pin* is the number of the pin being used for the photocell.

#### Methods

int value (); // Returns the current value (0-1023)
int value (int rangeStart, int rangeEnd) // Returns value mapped to specified range
int value (); // Returns the current value (0-1023)
int value (int rangeStart, int rangeEnd) // Returns value mapped to specified range

***Notes:***
*
The notes from the Knob section apply here.



- - -
## Speaker

In standard Arduino, speakers can be controlled using the tone() method. This is not available on the Trinket. So, the Speaker object implements related ways to make sound using one or two pins (see notes, below).

#### Declaration

Speaker mySpeaker(pin) // One speaker is pin, the other is ground
Speaker mySpeaker(pin1,pin2) // Speaker is connected between Pin1 and Pin2
Speaker speaker_name(pin); // One speaker is pin, the other is ground
Speaker speaker_name(pin1,pin2); // Speaker is connected between Pin1 and Pin2

***Notes:***

Often, a speaker is connected between one Arduino pin and ground. However, in the case of a Piezo, this can result in barely-audible audio. One technique to increase volume is to connect the speaker across two pins. This will drive the Piezo both positive and negative (rather than positive, then zero for a one-pin connection). This is handled by BobaBlox and results in double the volume.

#### Methods

void beep (frequency, length, color); // Beeps at frequency for length with color
void tone (frequency, color); // Continuous tone at frequency and color
void start (); // Starts tone (if it's been stopped)
void stop (); // Stops the tone (if its running)
void frequency (); // Returns the last set frequency
void color (); // Returns the last color
void beep (frequency, length, color); // Beeps at frequency for length with color
void tone (frequency, color); // Continuous tone at frequency and color
void start (); // Starts tone (if it's been stopped)
void stop (); // Stops the tone (if its running)
void frequency (); // Returns the last set frequency
void color (); // Returns the last color

***Notes:***

Expand All @@ -153,3 +174,40 @@ Often, a speaker is connected between one Arduino pin and ground. However, in th

*beep()* is just like the tone() Arduino function. It will pause the loop while the sound is playing.
*tone()* plays a tone continuously, monitoring it as the function is called repeatedly in *loop()*. In order for tone() to be effective, it must be called frequently at the top level of *loop()*.



- - -
## Timer

Sometimes in programming, you want to have timed actions that do not delay the main loop between actions. This is so you can continue checking a button, or blinking an LED, etc. The simple Timer object helps implement these "non-blocking" actions.

#### Declaration

Timer timer_name(); // Timer preset to 1 second
Timer timer_name(interval); // Timer preset to specified interval (milliseconds)

***Notes:***

To use a Timer, you can declare it with an interval, or use the setTime() or setTimeMicros() methods (below), then you use the start() method to begin the timer. Finally, the isExpired() method can be used to check when the timer has ended.

There are two versions of most routines, the "default" one that uses milliseconds, and a "micros" version that uses microseconds for higher resolution.

#### Methods

void setTime (time); // Sets the time (milliseconds)
void setTimeMicros (time); // Sets the time (microseconds)
void getTime (); // Returns the interval (milliseconds)
void getTimeMicros (); // Returns the interval (microseconds)
void getTimeRemaining (); // Returns the timer's remaining time (milliseconds)
void getTimeRemainingMicros (); // Returns the timer's remaining time (microseconds)
void start (); // Starts the timer
void restart (); // Same as start ()
void isExpired (); // Returns true if the timer has expired, false if not





- - -
Copyright 2015-2022 Robert Gallup
36 changes: 11 additions & 25 deletions examples/Button/Button.ino
View file
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
////////////////////////////////////////////
//
// BobaBlox Example Sketch: Button
// EZBlox Example Sketch: Button
//
// DECLARATION:
//
// Button myButton(pin) // pin = the pin connecting to the button
// Button myButton(pin); // pin = the pin connecting to the button
//
// METHODS:
//
// int state () // Returns 0 for up, 1 for down
// boolean isDown () // Returns true is button is down, false otherwise
// boolean isUp () // Returns true if button is up, false otherwise
// boolean wasPressed () // Returns true when a button is pressed
// boolean wasReleased () // Returns true when a button is released
// int state () // Returns 0 for up, 1 for down
// boolean isDown () // Returns true is button is down, false otherwise
// boolean isUp () // Returns true if button is up, false otherwise
// boolean wasPressed () // Returns true when a button is pressed
// boolean wasReleased () // Returns true when a button is released
//
////////////////////////////////////////////

#include <BobaBlox.h>

// Declarations
LED boardLED(1); // Use on-board LED
Button myButton(2); // Button is connected between pin #2 and Ground
LED boardLED; // Use on-board LED
Button myButton(2); // Button is connected between pin #2 and Ground

// Setup runs once
void setup() {
Expand All @@ -29,25 +29,11 @@ void setup() {
// Loop repeats forever
void loop() {

// If the button is down, turn LED on
if (myButton.isDown()) {
boardLED.on();
} else {
boardLED.off();
}

// To reverse the logic (light is on with up):
// Uncomment the following lines (and comment the lines above)

// if (myButton.isUp()) {
// boardLED.on();
// } else {
// boardLED.off();
// }

// Blink when button is pressed:

// if (myButton.isDown()) {
// boardLED.blink(1, 30, 70);
// }


}
26 changes: 11 additions & 15 deletions examples/Knob/Knob.ino
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,28 +13,27 @@
// | | |
// | | |
//
// 5V PIN GND
// Vcc PIN GND
//
//
// DECLARATION:
//
// Knob myKnob(pin) // pin is LED pin
// Knob myKnob(pin); // pin is LED pin
//
// METHOD:
// METHODS:
//
// int value (); // Returns the current value (0-1023)
// int value (int rangeStart, int rangeEnd) // Returns the current value mapped to range specified
// int value (); // Returns the current value (0-1023)
// int value (rangeStart, rangeEnd); // Returns the current value mapped to the specified range
//
////////////////////////////////////////////

#include <BobaBlox.h>

// Declarations
LED boardLED(1); // Declare an LED on pin #1
Knob myKnob(1); // Knob is connected to Analog pin #1 (digital pin #2)
LED boardLED; // Use the builtin LED
Knob myKnob(1); // Knob is connected to Analog pin #1

int knobValue; // The knob value
int blinkDelay; // The blink delay
int blinkDelay; // The blink delay

// Setup runs once
void setup() {
Expand All @@ -44,11 +43,8 @@ void setup() {
// Loop repeats forever
void loop() {

// Check the knob value
// Convert the value (0-1023) to a 0-1 second delay (0-1000).
// Note: see the Map command reference
knobValue = myKnob.value();
blinkDelay = map(knobValue, 0, 1023, 0, 1000);
// Check the knob value (converted to 0-1000) and use it for the blink delay
blinkDelay = myKnob.value(0, 1000);
boardLED.blink(1, blinkDelay);

}
}
Loading

0 comments on commit 74c64bb

Please sign in to comment.