Skip to content

Commit ba6cd53

Browse files
gigapodgigapod
authored
Merge pull request #4 from sparkfun/release/v1.1.0
Moves release v1.1.0 work to main
2 parents eff83f7 + 529177a commit ba6cd53

10 files changed

+613
-533
lines changed

‎README.md

Lines changed: 139 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,163 @@
1-
SparkFun Qwiic Buzzer Arduino Library [![Build Status](https://travis-ci.org/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library.svg?branch=master)](https://travis-ci.org/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library)
2-
========================================
31

4-
[![SparkFun Qwiic Buzzer](https://cdn.sparkfun.com/r/600-600/assets/parts/2/4/8/3/2/BOB-24474-Qwiic-Buzzer-Feature.jpg)](https://www.sparkfun.com/products/24474)
2+
![SparkFun Qwiic Buzzer](docs/images/gh-banner-2025-arduino-buzzer.png "SparkFun Qwiic Buzzer")
53

6-
[*SparkFun Qwiic Buzzer (BOB-24474)*](https://www.sparkfun.com/products/24474)
4+
# SparkFun Qwiic Buzzer
75

8-
<!---
6+
Arduino Library for the SparkFun Qwiic Buzzer breakout board
97

8+
![License](https://img.shields.io/github/license/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library)
9+
![Release](https://img.shields.io/github/v/release/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library)
10+
![Release Date](https://img.shields.io/github/release-date/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library)
11+
![Documentation - build](https://img.shields.io/github/actions/workflow/status/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library/build-deploy-ghpages.yml?label=doc%20build)
12+
![Compile - Test](https://img.shields.io/github/actions/workflow/status/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library/compile-sketch.yml?label=compile%20test)
13+
![GitHub issues](https://img.shields.io/github/issues/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library)
1014

11-
UPDATE WHAT DOES THIS LIBRARY DO!?! =)
1215

16+
The [SparkFun_Qwiic_Buzzer_Arduino_Library (BOB-24474)](https://www.sparkfun.com/sparkfun-qwiic-buzzer.html) adds simple beeps and buzzes to your projects via I2C. Make some noises to alert you when something interesting (or urgent) happens. Simply connect a Qwiic cable and load up some pre-written code to an Arduino to start making noises!
1317

18+
The board includes an ATtiny84 with custom firmware to control the magnetic buzzer over I2C. Utilizing our handy Qwiic system, no soldering is required to connect it to the rest of your system. However, we still broke out 0.1"-spaced PTH pads if you prefer to use a breadboard to access the board's I2C, power, trigger, and reset pins on the board's edge. A 2.2k&ohm; pull-up resistor is included on the data and clock lines.
1419

15-
This library allows the user to:
20+
Looking for the board that matches this library - pick up a [SparkFun Qwiic Buzzer (BOB-24474)](https://www.sparkfun.com/sparkfun-qwiic-buzzer.html) at www.sparkfun.com.
1621

17-
* Turn the buzzer on and off directly
18-
* Optionally, set the frequency, duration, and volume of the sound
19-
* Adjust the device's I<sup>2</sup>C address
22+
## Functionality
2023

21-
-->
24+
This library provides an interface that enables the following functionality when a SparkFun Qwiic Buzzer breakout board:
2225

23-
Repository Contents
24-
-------------------
26+
* Turn the buzzer on and off
27+
* Adjust the buzzers frequency and duration
28+
* Control the the volume of the buzzer
29+
* Play sound effects on the buzzer
30+
* Change the I2C address to enable the use of multiple buzzers on one device
2531

26-
* **/examples** - Example sketches for the library (.ino). Run these from the Arduino IDE.
27-
* **/src** - Source files for the library (.cpp, .h).
28-
* **keywords.txt** - Keywords from this library that will be highlighted in the Arduino IDE.
29-
* **library.properties** - General library properties for the Arduino package manager.
3032

31-
Documentation
32-
--------------
33+
## General Use
34+
The following outlines the general use of the library in an Arduino Sketch.
3335

34-
* **[Installing an Arduino Library Guide](https://learn.sparkfun.com/tutorials/installing-an-arduino-library)** - Basic information on how to install an Arduino library.
35-
* **[Product Repository](https://github.com/sparkfun/SparkFun_Qwiic_Buzzer)** - Main repository (including hardware files) for the SparkFun Qwiic Buzzer Breakout Board.
36-
* **[Hookup Guide](https://docs.sparkfun.com/SparkFun_Qwiic_Buzzer)** - Basic hookup guide for the Qwiic Buzzer.
36+
### Declaration
3737

38-
Products that use this Library
39-
---------------------------------
38+
At the start of your sketch, the library header file is included using the following statement:
4039

41-
* [*BOB-24474*](https://www.sparkfun.com/products/24474) - Initial release
40+
~~~cpp
41+
#include <SparkFun_Qwiic_Buzzer_Arduino_Library.h>
42+
~~~
4243

43-
Version History
44-
---------------
44+
Before the arduino ```setup()``` function, create a Buzzer object in your file with the following declaration:
4545

46-
* v1.0.0 - Initial Public release.
46+
~~~c
47+
QwiicBuzzer buzzer; // its a buzzer
48+
~~~
4749

48-
License Information
49-
-------------------
5050

51-
This product is _**open source**_!
51+
### Initialization
5252

53-
Please review the LICENSE.md file for license information.
53+
In the Arduino ```setup()``` function, initialize the buzzer by calling the begin method. This method is called after the Arduino `Wire` (I2C) library is initialized.
5454

55-
If you have any questions or concerns on licensing, please contact technical support on our [SparkFun forums](https://forum.sparkfun.com/viewforum.php?f=152).
55+
~~~cpp
56+
//check if buzzer will connect over I2C
57+
if (buzzer.begin() == false) {
58+
Serial.println("Device did not connect! Freezing.");
59+
while (1);
60+
}
61+
~~~
62+
63+
The begin method returns true if the buzzer is connected and available, and false if it is not. If a value of *false* is returned in the above example, the sketch execution is halted.
64+
65+
### Usage
66+
67+
#### On/Off
68+
69+
Turn the buzzer on and off as shown in the following loop example:
70+
71+
~~~cpp
72+
void loop() {
73+
buzzer.on();
74+
75+
delay(1000);
76+
77+
buzzer.off();
78+
79+
delay(1000);
80+
}
81+
~~~
82+
83+
#### Frequency Control
84+
85+
The buzzer frequency is controlled using the ```configureBuzzer()``` method.
86+
87+
~~~cpp
88+
void loop() {
89+
// Configure with desired settings
90+
// Resonant frequency is 2.73KHz
91+
buzzer.configureBuzzer(SFE_QWIIC_BUZZER_RESONANT_FREQUENCY);
92+
buzzer.on();
93+
delay(100);
94+
95+
buzzer.off();
96+
delay(1000);
97+
98+
buzzer.configureBuzzer(1000); // set frequency to 1KHz
99+
buzzer.on();
100+
delay(100);
101+
102+
buzzer.off();
103+
delay(1000);
104+
}
105+
~~~
106+
107+
#### Buzz Duration
108+
109+
The buzz duration is set by adding a timing value after the frequency to the ```configureBuzzer()``` method.
110+
111+
~~~cpp
112+
buzzer.configureBuzzer(2730, 100); // frequency: 2.73KHz, duration: 100ms
113+
~~~
114+
115+
#### Volume
116+
117+
The buzz volume is an additional optional parameter to the ```configureBuzzer()``` method.
118+
119+
~~~cpp
120+
buzzer.configureBuzzer(2730, 100, SFE_QWIIC_BUZZER_VOLUME_MIN); // frequency: 2.73KHz, duration: 100ms, volume: MIN
121+
...
122+
buzzer.configureBuzzer(2730, 100, SFE_QWIIC_BUZZER_VOLUME_MAX); // frequency: 2.73KHz, duration: 100ms, volume: MAX
123+
~~~
124+
125+
#### Sound Effects
126+
127+
The buzzer has a collection of sound effects included in this library. These are started by using the ```playSoundEffect()``` method, providing the number of the sound effect to play.
128+
129+
Playing sound effect 1:
130+
131+
~~~cpp
132+
err = buzzer.playSoundEffect(1, BUZZER_VOLUME);
133+
~~~
134+
## Examples
135+
136+
The following examples are provided with the library
137+
138+
- [Buzz](examples/Example_01_Buzz/Example_01_Buzz.ino) - This example shows how to turn the buzzer on and off.
139+
- [Buzz Frequency](examples/Example_02_Buzz_Frequency/Example_02_Buzz_Frequency.ino) - This example shows how to adjust the frequency of the buzzer.
140+
- [Buzz Duration](examples/Example_03_Buzz_Duration/Example_03_Buzz_Duration.ino) - This example shows how to control the buzzer using frequency and duration.
141+
- [Buzz Volume](examples/Example_04_Buzz_Volume/Example_04_Buzz_Volume.ino) - This example shows how to control the buzzer to sound at different volumes.
142+
- [Change I2C Address](examples/Example_05_ChangeI2CAddress/Example_05_ChangeI2CAddress.ino) - A configurator for changing the I2C address on the Qwiic Buzzer that walks the user through finding the address of their buzzer, and then changing it!
143+
- [Save Settings](examples/Example_06_SaveSettings/Example_06_SaveSettings.ino) - This example shows how to save settings to the buzzer.
144+
- [Melody](examples/Example_07_Melody/Example_07_Melody.ino) - TThis example shows how to buzz a melody on the Qwiic Buzzer.
145+
- [Sound Effects](examples/Example_08_Sound_Effects/Example_08_Sound_Effects.ino) - This example demos the sound effects included in this library.
146+
- [Firmware Version](examples/Example_09_FirmwareVersion/Example_09_FirmwareVersion.ino) - This example shows how to read the firmware version from the Qwiic Buzzer
147+
- [Buzz Multiple](examples/Example_10_Buzz_Multiple/Example_10_Buzz_Multiple.ino) - This example shows how to control multiple buzzers.
148+
149+
## Documentation
150+
151+
The full API and use documentation for this library is provided [here](https://docs.sparkfun.com/SparkFun_Qwiic_Buzzer_Arduino_Library/). For a quick reference, the main methods available in the library are listed [here](https://docs.sparkfun.com/SparkFun_Qwiic_Buzzer_Arduino_Library/class_qwiic_buzzer.html).
152+
153+
Curious about the hardware this board works with - visit the SparkFun Qwiic Buzzer [hardware repository](https://github.com/sparkfun/SparkFun_Qwiic_Buzzer).
154+
155+
The ***Hookup Guide*** for the SparkFun Qwiic Buzzer is available [here](https://docs.sparkfun.com/SparkFun_Qwiic_Buzzer).
156+
157+
## License Information
158+
159+
This product is ***open source***!
160+
161+
This product is licensed using the [MIT Open Source License](https://opensource.org/license/mit).
56162

57-
Distributed as-is; no warranty is given.
58163

‎docs/images/gh-banner-2025-arduino-buzzer.png

381 KB
Loading

‎library.properties

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
name=SparkFun Qwiic Buzzer Library
2-
version=1.0.1
2+
version=1.1.0
33
author=SparkFun Electronics <techsupport@sparkfun.com>
44
maintainer=SparkFun Electronics <support@sparkfun.com>
55
sentence=Communicates with and configures the SparkFun Qwiic Buzzer
66
paragraph=This library allows the user to control the buzzer frequency/duration, and change its I2C addresses.
77
category=Outputs
88
url=https://github.com/sparkfun/SparkFun_Qwiic_Buzzer_Arduino_Library
99
architectures=*
10-
depends=SparkFun Toolkit (<1.0.0)
10+
depends=SparkFun Toolkit (>=1.0.0)

‎src/SparkFun_Qwiic_Buzzer_Arduino_Library.h

Lines changed: 22 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,26 @@
1-
/******************************************************************************
2-
SparkFun_Qwiic_Buzzer_Arduino_Library.h
3-
SparkFun Qwiic Buzzer Library header file
4-
5-
by Pete Lewis @SparkFun Electronics
6-
January 2024
7-
8-
Based on original source code written by
9-
Fischer Moseley @ SparkFun Electronics
10-
Original Creation Date: July 24, 2019
11-
12-
This file implements the QwiicBuzzer class, prototyped in SparkFun_Qwiic_Buzzer_Arduino_Library.h
13-
14-
Development environment specifics:
15-
IDE: Arduino 2.2.1
16-
Hardware Platform: Arduino Uno/SparkFun Redboard
17-
Qwiic Buzzer Version: v10
18-
19-
SPDX-License-Identifier: MIT
20-
21-
Copyright (c) 2024 SparkFun Electronics
22-
23-
Distributed as-is; no warranty is given.
24-
******************************************************************************/
1+
/**
2+
* @file SparkFun_Qwiic_Buzzer_Arduino_Library.h
3+
* @brief SparkFun Qwiic Buzzer Library header file
4+
* @author Pete Lewis \@SparkFun Electronics
5+
* @date January 2024
6+
*
7+
* @note Based on original source code written by Fischer Moseley \@ SparkFun Electronics
8+
* Original Creation Date: July 24, 2019
9+
*
10+
* @details This file implements the QwiicBuzzer class, prototyped in SparkFun_Qwiic_Buzzer_Arduino_Library.h
11+
*
12+
* @copyright Copyright (c) 2024 SparkFun Electronics. This project is released under the MIT License.
13+
* @license SPDX-License-Identifier: MIT
14+
*
15+
*/
2516

2617
#pragma once
2718

28-
#include "sfeQwiicBuzzer.h"
19+
// clang-format off
2920
#include <SparkFun_Toolkit.h>
30-
31-
class QwiicBuzzer : public sfeQwiicBuzzer
21+
#include "sfTk/sfDevBuzzer.h"
22+
// clang-format on
23+
class QwiicBuzzer : public sfDevBuzzer
3224
{
3325
public:
3426
/// @brief Begins the Qwiic Buzzer
@@ -41,16 +33,16 @@ class QwiicBuzzer : public sfeQwiicBuzzer
4133
_theI2CBus.init(wirePort, address);
4234

4335
// Begin the sensor
44-
return sfeQwiicBuzzer::begin(&_theI2CBus) == kSTkErrOk;
36+
return sfDevBuzzer::begin(&_theI2CBus) == ksfTkErrOk;
4537
}
4638

4739
/// @brief Checks if the Qwiic Buzzer is connected
4840
/// @return True if the sensor is connected, false otherwise
4941
bool isConnected()
5042
{
51-
return sfeQwiicBuzzer::isConnected() == kSTkErrOk;
43+
return sfDevBuzzer::isConnected() == ksfTkErrOk;
5244
}
5345

5446
private:
55-
sfeTkArdI2C _theI2CBus;
47+
sfTkArdI2C _theI2CBus;
5648
};

0 commit comments

Comments
 (0)