sparkfun Spectacle Technical document

Spectacle Sound Kit Hookup Guide


Introduction
The Spectacle Sound Kit contains everything you need to make a button-
triggered sound-playback project.
Suggested Reading
Before proceeding, you should read through the Spectacle User’s Guide. It
will give you the basics you’ll need to know about how Spectacle works to
follow the rest of this tutorial.
Spectacle Audio Board
The Spectacle Audio Board allows you to add sound to your Spectacle
projects. It accepts a microSD card with sounds in .ogg format (more on
this later), and has a 1/8" (3.5mm) audio jack to connect to external
amplifiers.
Spectacle Sound Ki
t

KIT-14172
Page 1 of 2
2

tl;dr
1. Audio files for Spectacle should be formatted as .ogg files.
2. Audio files should have names 00.ogg, 01.ogg, 02.ogg, etc.
3. The audio jack on the Audio Board produces output suitable for
amplification only. It is not suited to headphones or unpowered
speakers.
Meet the Spectacle Audio Board
Designed to be a low-cost and easy to use method of adding sound to
projects, the Spectacle Audio Board integrates with the rest of the
Spectacle ecosystem to provide sound effects on demand.
It has three 1/8" (3.5mm) jacks: two for Spectacle control signals and one
for the audio output. Be certain you are plugging cables into the right
jacks! Plugging an audio device into one of the Spectacle jacks could
cause damage to the audio device. Note that the Spectacle data jacks are
directional: the one marked “In” should be plugged into the “upstream”
board (i.e., closer to the Director Board than this one) and the one marked
“Out” connects to the next downstream board. The “Out” jack is not for
audio signals.
The audio output is designed for amplified devices only. This means that
any attempt to use the Spectacle Audio Board with headphones or
unamplified speakers will fail to produce audible output. SparkFun sells a
small, amplified, rechargeable speaker which is specifically intended for use
with the Spectacle Audio Board.
Spectacle Audio Boar
d

DEV-14034
Page 2 of 2
2

The Spectacle Audio Board uses a Micro SD card to store the audio files to
be played. The files should be stored as .ogg Vorbis encoded files. This
free audio file format can be played and created on any type of computer.
Later in the tutorial we’ll show you how to convert from MP3, WAV, or other
file formats to the .ogg format.
The files must be named by number, which is how they will be referred to
from within the configuration application. Filename examples are 00.ogg,
01.ogg, 02.ogg, and so forth.
Spectacle Button Board
The Spectacle Button Board allows you to add input from buttons or
switches to your Spectacle projects. It has a total of 9 signal inputs, eight of
which can come from external buttons and one button directly on the board.
tl;dr
1. Buttons or switches can be connected to the board by pushing wires
into the “poke home” type connectors on the board.
2. Up to nine signals are available.
3. Button signals can be either momentary or continuous.
Meet the Spectacle Button Board
Spectacle Button Boar
d

DEV-14044
Page 3 of 2
2

Designed to bring simple signals from the world into your Spectacle
projects, the Spectacle Button Board provides input for any of your
Spectacle projects.
It has two 1/8" (3.5mm) jacks for connecting to other boards in a Spectacle
system. Note that the Spectacle data jacks are directional: the one marked
“In” should be plugged into the “upstream” board (i.e., closer to the Director
Board than this one) and the one marked “Out” connects to the next
downstream board.
There are 8 “poke home” connectors on the Button Board. Each one can be
connected to one (or more) buttons. To add a connection, simply push the
stripped end of a wire into the hole on the connector. The connector will
automatically grab on and hold the wire in place. If you need to remove the
wire later, an small object (bobby pin, ballpoint pen, etc.) can be used to
depress the release button, allowing the wire to be extracted without
damage.
There is an input button on the button board itself which can be used to
provide an input signal if no other buttons are available. It functions like any
other normal button that might be attached. Be certain you’re pressing
the button labeled ‘8’ and not the one labeled ‘Reset’! Pressing the
reset button will reset your button board, probably causing your entire
system to stop working properly until you reset your Director Board!
The Configuration Utility
Spectacle Sound Board
Page 4 of 2
2

The Spectacle Audio Board only supports one action: Play Sound. As you
can see above, there are a number of settings associated with this action.
•“Listen to channel number…” - This is the channel number which
triggers the audio to start playing. As long as this channel’s value is
above the threshold level (see below), the sound will repeat playing
at a rate determined by the two time intervals specified lower down.
•“wait … seconds and play…” - This is the first delay in the system.
By delaying when a sound plays, you can sequence events however
you see fit.
•“…and play file number…” - This is where you tell the board which
file to play. Remember, when copying the audio files to the Micro SD
card, they should be named as 00.ogg, 01.ogg, 02.ogg, etc. The
number in this field corresponds to the number in the name of the
audio file. If there is no audio file with the corresponding number, no
sound will play.
•“do not allow another sound to interrupt until … seconds” - The
number in this field should correspond to the length of the audio file.
If this value is less than the length of the sound file, another trigger
sent to the audio board will interrupt the sound before it finishes. If it
is longer than the sound, there will be a period of silence after
playback before another playback can be initiated.
•“activation threshold” - As it says in the app, most of the time you
don’t need to adjust this. By tweaking this, you can set the angle at
which the Spectacle Accelerometer Board triggers a sound, or the
frequency with which a Random Trigger Virtual Board causes a
sound to play.
Spectacle Button Board
Page 5 of 2
2

For the Button board, there are five options: three which produce a
momentary pulse type output and two that produce a continuous switch
type output.
Action on press
Trigger an action when a button is first pressed, regardless of how long it is
subsequently held down.
•“When button number … is pressed” - This is the number of the
button we wish to assign to this action. The button numbers are
printed on the board, and run from 0 through 8.
•“trigger channel number …” - A single, momentary pulse will be
sent out on this channel. It is suitable for starting a sound, initiating a
motion, or setting the color of a light strip, but not for continuous
sound playback or for turning on a light strip effect, for instance.
Action on release
Page 6 of 2
2

Trigger an action when a button is released, regardless of how long it has
been held down prior to being released.
•“When button number … is released” - This is the number of the
button we wish to assign to this action. The button numbers are
printed on the board, and run from 0 through 8.
•“trigger channel number …” - A single, momentary pulse will be
sent out on this channel. It is suitable for starting a sound, initiating a
motion, or setting the color of a light strip, but not for continuous
sound playback or for turning on a light strip effect, for instance.
Action on press or release
Trigger an action when a button is pressed, then trigger the same action
again when the button is released.
•“When button number … is either pressed or released” -Thisis
the number of the button we wish to assign to this action. The button
numbers are printed on the board, and run from 0 through 8.
•“trigger channel number …” - A single, momentary pulse will be
sent out on this channel both at the time the button is pressed and at
the time it is released. It is suitable for starting a sound, initiating a
motion, or setting the color of a light strip, but not for continuous
sound playback or for turning on a light strip effect, for instance.
Action while holding
Page 7 of 2
2

Trigger an event as soon as a button is pressed, then continue to trigger
that event as long as the button is held down.
•“While button number … is pressed” - This is the number of the
button we wish to assign to this action. The button numbers are
printed on the board, and run from 0 through 8.
•“activate channel number …” - A continuous will be sent out on
this channel. It is suitable for triggering and repeating a sound, or for
turning on and keeping on (at least, while the button is held) a
lighting effect.
Latch On/Latch Off
This action is like a latching power switch. One press turns the signal on,
another later press turns the signal off.
•“While button number … is pressed” - This is the number of the
button we wish to assign to this action. The button numbers are
printed on the board, and run from 0 through 8.
•“activate channel number … until button is pressed again” -A
continuous will be sent out on this channel. It is suitable for triggering
and repeating a sound, or for turning on and keeping on a lighting
effect.
Converting Sounds to OGG Vorbis
Page 8 of 2
2

Forma
t
The files used by the Spectacle Audio Board must be in OGG Vorbis
format. This free, lossy codec has a higher compression ratio than MP3,
and, more importantly, can be used without paying a licensing fee to any
third part organization.
Download and Install Audacity
We’ll be using the free, open source program “Audacity” to convert from
whatever your file’s current format is to OGG Vorbis.
Audacity is available across all three major operating systems, so you
shouldn’t have any trouble getting it installed.
When you start Audacity, you’ll see this screen, or one very like it. While at
first blush it seems extremely complex, none of this crap is important to
us, so don’t panic.
Load a file
Like most programs, “loading a file” just means selecting “Open” from the
File menu and choosing which file you wish to convert. Audacity is capable
of editing most types of audio files: WAV, AIFF, FLAC, MP3, and others.
By default, Audacity shows all files, not just compatible audio files, when
you bring up the open dialog. There’s a dropdown menu that allows you to
change that so it shows only compatible audio files along the bottom edge
of the window.
Page 9 of 2
2

Once you select which file you wish to edit, a rather alarmist message may
pop up warning you about editing files without making a copy of them. Just
click “OK”.
You’ll see, then, something like this show up. This is what your audio file
looks like, to the computer. Again, don’t panic! Unless you want to edit the
sound in some way (which we don’t), none of the settings or pieces of
information that have popped up here matter to us.
Convert to OGG
Now that you have the file loaded, you need to convert it to OGG Vorbis
format. To do so, open the “File” menu and select the “Export Audio…”
menu item about halfway down. A familiar looking save window should pop
up.
Right below the “File name:” field you’ll see a drop-down menus labeled
“Save as type:”. Select “Ogg Vorbis Files” in that drop down.
A slider will appear at the bottom of the window. The default value of ‘5’ is
probably good enough for most purposes. Click “Save” and another window
will pop up.
Page 10 of 2
2

This one allows you to set metadata about the file. You can ignore
everything and just click “OK” to skip past this.
Congratulations! You’ve successfully converted a file to OGG Vorbis
format. You may now copy that file to the Micro SD card (don’t forget to
rename it to a number!) for use with the Spectacle Audio Board.
Extra credit- trimming the fat and making the sound louder
As you can see in my file above, there’s a great deal of room between the
extents of the sound and the extents of the window. In the time (horizontal)
axis, this manifests as flat lines before and after the content of the sound
file. In the “loudness” (vertical) axis, this manifests as space between the
top and bottom of the waveform file and the top and bottom of the playback
position window.
Let’s eliminate some of that dead time before and after the sound plays. To
do so, simply click inside the playback position window and drag, as though
you are trying to select a section of text. The part you’ve selected will be
highlighted, as above. Now, just hit the “Delete” key on your keyboard, and
that section will be removed. Repeat the process at the other end of the
sound.
Page 11 of 2
2

Now, let’s see what we can do about volume. Under the “Edit” menu, look
for the “Select” submenu, and choose “All” to select the entire sound. You
can also just use the drag-and-highlight method from above.
Now that you’ve got the entire sound selected, click on the “Effect” menu
and select the “Amplify…” option.
A new window will pop up with a slider, a couple of text boxes, and one
checkbox. The slider will be pre-positioned to amplify the sound as much as
possible without “clipping” it. “Clipping” occurs when you try to amplify a
sound more than the system you’re playing it through can stand, and it
results in a sort of grating buzzing noise during playback.
You have a choice, now: you can either accept the system’s suggested
level, or you can click on the “Allow Clipping” check box and increase the
amplification more with the slider. I’ve chosen to accept the clipping
limitation for the image above; comparing it to the image of the file higher
up, you can see how I’ve trimmed the dead time at the ends and increased
the amplitude vertically.
Why would you want to allow your sound to clip? Well, first of all, the preset
amplification only takes into account the peak value of your sound, so if one
small section of the audio is allowed to clip, it may allow the vast majority of
the sound to be substantially louder. Secondly, if you’re playback device is
Page 1
2
of 2
2

of relatively poor quality, or the sound file itself is, allowing clipping may
increase volume significantly without making the sound quality too much
worse than it already is. Thirdly, volume intensity may be far more important
than sound quality, and allowing clipping lets you push the volume as high
as you can.
Now that you’ve successfully edited the sound, export it to OGG Vorbis as
we covered above.
Example Project
Let’s use the contents of the Spectacle Sound Kit to put together a working
project!
Connect the boards
All of the required hardware for this tutorial is included in the kit.
Start by connecting up the boards. You’ll need the included TRRS audio
cables, the power supply, and the small, rechargeable speaker. Make sure
the speaker is charged before the first time you try to use it!
First, plug one end of one of the TRRS cables into the “Direct” jack on the
Director Board.
Next, take the other TRRS cable and plug it into the “Program” jack on the
Director Board.
Take the other end of this cable and plug it into the audio jack of the phone,
tablet, or computer that you’ll be using to program the system.
Page 1
3
of 2
2

Then take the other end of the first TRRS cable (the one connected to the
“Direct” jack on the Director Board) and plug it into the “In” jack on the
Button board.
Grab another of the TRRS cables and plug it into the “Out” jack on the
button board.
Plug the other end of that cable into the “In” jack on your Audio board.
Now plug the speaker into the “Audio Out” jack on the Audio board.
Page 1
4
of 2
2

You can now insert the micro SD card into the slot on the back of the board.
Finally, plug the Micro B end of the power adapter into the Director board,
and the other end into the wall. You should see one solid light and one
blinking light on both the Audio board and the Button board. On the Director
board, you’ll see one solid light and one light which blinks eight times, then
pauses, then repeats. This shows that power is present and the boards are
up and running.
Setting up the board configuration
We’re going to assume that you followed the instructions on the previous
page about converting sounds to OGG Vorbis format, and that there is a
sound on the Micro SD card inserted into the Sound board named “00.ogg”.
If this is not the case, take a few minutes to go back to that page and
prepare a sound.
Here’s a new project in the spectacle app screen. Feel free to rename
yours (it will have a different default name than the example does), as the
name of the project has no effect on the rest of the process.
Click the button highlighted below to add a board to our system’s
configuration.
Page 1
5
of 2
2

Click anywhere in the “Button” box in the list that pops up to add a Button
Board to your project. Now, repeat the process and click in the “Audio” box
to add an Audio Board to your project.
You’ll be back to the main page, then, but there will be a couple of new
lines present: one for the Button Board and one for the Audio Board.
Page 1
6
of 2
2

To edit the actions assigned to these boards, click on the clapboard icon in
the row of the board you wish to edit. We’ll start by editing the Button
Board’s actions.
Any time you bring up a new board to add actions, you’ll see the same
screen as below. To add an action, click the “Add An Action” button in the
center bottom of the frame.
Page 1
7
of 2
2

This will present you with a list of actions that the current board is capable
of implementing. In the case of the button board, there are five different
options. Click on the first one, “Action on Press”.
You’ll now see the window as above. Put a ‘0’ in the two fields indicated,
causing a trigger pulse to be sent out on channel 0 whenever button 0 is
pressed. Then click the “Go Back” button at the bottom of the page to save
the action and return to the main page.
Page 18 of 2
2

Back on the main page, you can see that the action you added is visible on
the Button Board’s row in the window. Let’s edit the actions for the Sound
board next.
There’s only one option for actions for the Audio Board, and that’s “Play
Sound”. Once you’ve clicked through to the configuration window for “Play
Sound”, you’ll see a page like this. Fill in the blanks as shown above, then
click the “Go Back” button again.
Page 1
9
of 2
2

You’ll be back on the main page, now, and you’ll see the actions you’ve
added under each of the lines in the project. It’s time to upload the
configuration to your hardware!
Uploading
Now that you’ve created your Spectacle program it’s time to upload it to the
Director Board. If you followed the instructions above, your uploading
device is connected to the board and ready to go, so all you need to do is
touch the “Install Script” button at the bottom of the page. That will bring up
the page seen below.
Page 20 of 2
2