For Users

TuneStudio2560 User Guide

This guide is meant for users who are looking at how to use TuneStudio2560 and its controls.

Prologe

Thank you for checking out the official user guide.
The User Guide will go over the controls and quirks of TuneStudio2560.
For a visual explanation please check out the video tutorials of using TuneStudio2560 which are available on the reference website.

What is it?

TuneStudio2560 is a song creation and playback device which allows users to create, edit, and delete songs.
Each song in TuneStudio2560 is stored on a microSD card for fast access.
Using TuneStudio2560 allows users to add a series of linear pitches to their song in sequence.
All pitches which can be added to TuneStudio2560 use the standard chromatic scale.

Note that I use pitch, tone, and tune interchangeably frequently.

Supported Microcontrollers

• Arduino Mega2560 (16MHz, 8KB SRAM, 256KB Storage).

View README.md for parts overview

Simple Hardware Overview

20x4 LCD: Provides visual feedback when using the application.

Tune Buttons: Represent different frequency ranges that users can user when creating songs. Each tune button has a corresponding LED that lights up when the button is pressed. Sometimes, tune buttons may be used for controls.

Control Buttons: Three buttons (Select/Add, Delete/Cancel, Option) used for navigation throughout TuneStudio2560. The actions which are invoked on button presses may differ depending on the current state of the application.

Piezo Active Speaker: Provides simple 8-Bit audio to the user. Only one frequency can be played at once. TuneStudio2560 can play frequencies between 31Hz and 3951Hz.

RGB Status LED: Useful for direct user feedback. The LED may light up on application errors or may also signal when the Option Button is pressed.

Potentiometer: Allows a user to select different tones for each individual tune button. Can also be used for naming songs.

4 Digit 7 Segment Display: Provides feedback on which tone the user is going to add to their application when they are creating a song.

What can it do?

Here are some of the features available in TuneStudio2560:

• Navigation using easy to understand buttons allows seamless switching between different parts of the program.
• Song creation tool uses standard chromatic notes which are visible to the user when creating a song.
• Song creation tool contains features such as playing back the song you have created as well as saving your song to an SD card with a custom name.
• Listening mode allows users to play songs on their SD card. TuneStudio2560 can distinguish proper and correctly formatted songs from other files.
• Listening mode grants users media playback tools when listening to their song such as pause, forward, rewind as well as a convenient progress bar.
• 4 Digit 7 Segment display tells the user which tone they are about to add to their song in the song creatior.
• RGB status LED indicates errors and feedback from the program.
• Songs can be edited on a PC from the microSD card.
• Songs can be created right from the microSD card on a PC and then played back on TuneStudio.
• The tone length and tone durations of each song can be changed when editing the microSD card.

How Songs Work

Songs are made up of individual frequencies between 31Hz and 3951Hz.
Up to 255 (default) tones can be added to a song by default. When a song is played, each tune in the song is played for tone duration milliseconds and after that a short delay known as the tone delay is started. During the tone delay, no music is played (like a short pause).
Both the tone delay and tone length for each song can be adjusted using the microSD file on a computer.
Songs can also contain pauses (500ms each) in which no sound is played. Pauses can be added in Creator Mode when making a song.

When a song is saved, it is loaded into its own .txt file on the microSD card where it remains until it is deleted or overwritten.
Songs use a custom file format to communicate directly with the Arduino. This file format can be modified on a PC.
While modifying a song, a user can add, delete, edit, adjust the tone length/delay, as well as type their own comments using a hashtag "#". Comments generated in this file will not be read by the program.
All songs should be stored in the root "/" directory of the SD card. The program will not read folders.

Mode Explanations

Main Menu

The first screen you will see when TuneStudio2560 is first started.
Provides inital information on how the program works as well as a link to this GitHub repository.

Creator Mode

Allows a user to create their own song using an interactive menu.
Users can click on one of the five tune buttons to play a frequency.
The tune buttons are arranged as follows:

1. Tune Button #1 (Lowest Pitch)

• Color: GREEN
• Frequency Range: 31Hz-78Hz

2. Tune Button #2

• Color: BLUE
• Frequency Range: 82Hz-208Hz

3. Tune Button #3

• Color: RED
• Frequency Range: 220Hz-554Hz

4. Tune Button #4

• Color: YELLOW
• Frequency Range: 587Hz-1480Hz

5. Tune Button #5 (Highest Pitch)

• Color: WHITE
• Frequency Range: 1568Hz-3951Hz

Clicking on a TuneButton will play its current frequency. Current frequency is calculated based on the tone button which was last pressed along with the value of the potentiometer.

The potentiometer (frequency adjuster) allows the fine tuning of each of the tune buttons.
Each tune button represents 17 different states within its specified frequency range.

The 7 segment display will display the value of the current tune. The display updates every time a tune button is pressed or the potentiometer is turned. When tune buttons are added, they are displayed on the LCD. Tunes can be removed by pressing the delete button.
Pauses can also be added to the song via the option button and the blue tune button.
When the amount of tunes on a single page reaches its maximum, the display will allow you to scroll row by row with a double press of the option button.
The current row you are on is displayed at the first line of the lcd in square brackets.
The current songs length, along with the max song length is also displayed on the same row.
When finished a song can be saved and then named using the potentiometer to cycle through characters A-Z, 0-9, and underscores.
Songs being worked on in Creator Mode can also be played back.

Listening Mode

Searches the SD card for any possible songs and displays a selection menu on the LCD.
Songs can be selected using the five tune buttons.
Songs are each given a number corresponding to their position on the SD card.
To select a song above #5 a user can cycle pages via the option button. (ex. Page 1: Songs 1-5 can be selected, Page 3: Songs 11-15 can be selected).
Each songs name is set when it is first made in Creator Mode.
When a song is selected, the program scans the song for any errors and then begins playing it. If an unchecked error occurs while parsing from the SD card, the program will crash and a restart is required.
When inside the playback screen, a user can pause the song, rewind, and fast forward to different parts. The Progress Bar provides a easy to read interface for determining how far in the song a user is.
Listening Mode also displays the information about the song while in the playback screen. Data such as the tone length, tone duration, song length, song number, and the page number the song is located in are displayed.
Songs can also be deleted in Listening Mode (see controls).

Controls

This section details all possible controls that can be used in TuneStudio2560.
Note that the controls for each section are detailed upon changing modes. This section serves as a simple guide for controls without having to read the LCD.

Button Arrangements:
All control buttons are located to the right of the tune buttons.

Select Button: Left button.
Delete Button: Middle button.
Option Buton: Right button.
Note that in Creator Mode, the status LED turns Blue when the option button is pressed and the next press will utilize the option button if possible.

Main Menu Controls

SELECT: Enter Creator Mode.

DELETE: Enter Listening Mode.

Listening/Creator Mode Instruction Menu Controls

SELECT: Skip instructions.

DELETE: Return back to home screen.

Creator Mode Controls

Tune Button: Listen to a tune based on the button pressed and the value of the potentiometer.

Potentiometer: Change the tune based on the last tune button pressed. Tunes can be viewed on the segment display.

SELECT: Add the current tune viewed on the segment display to the song.

DELETE: Delete the last tune added to the song.

OPTION: Double press to cycle between pages. RGB Led becomes blue on Option Press.

OPTION+GREEN Tune: Playback the current song.

OPTION+Blue Tune: Add a pause to the song. "PS" on segment display.

OPTION+DELETE: Exit Creator Mode (will not save song).

OPTION+SELECT: Opens the saving menu where a name must be given. After a name is given Option+Select must be pressed again to finalize. To cancel, Option+Delete can be used to exit the naming menu. Using the potentiometer can cycle through characters on the naming menu.

Listening Mode Controls

Song Selection

SELECT: Play current song selected.

DELETE: Return to Main Menu.

Tune Buttons: Select a song depending on the page.

OPTION: Cycle pages.

Playback

SELECT: Pause/Play song.

GREEN Tune: Go forward in the song when paused.

BLUE Tune: Go backward in the song when paused.

DELETE: Exit to Main Menu.

OPTION+DELETE: Delete the current song (uses confirm prompt). Note that both the option button and the delete button must be pressed at the same time.

SD Card & Song Modification outside of TuneStudio2560

TuneStudio2560 allows the editing, creation and deletion of songs outside of the device.
To do this, insert the microSD into your main PC and open the .txt file that corresponds with the name of your song.
The file is quite readable and is meant to be user friendly. Notepad++ is a recommended text editor for editing these files.
You will also find a README.txt file. It is recommended to view this file and its contents before editing any of your song files.

IMPORTANT
ENSURE THAT ALL SONG FILE NAMES ARE NO LONGER THEN EIGHT (8) CHARACTERS IN LENGTH FOLLOWED BY A ".TXT" (Not included in length).

Add/Delete Songs

• Users can add or delete songs from the microSD.
• When adding songs ensure that they are the correct format.
• You may also copy songs in the root directory to make copies.

Add/Remove/Edit Pitches:

• View the "Supported Pitches" in Extra Information for all pitches that are supported.
• Add a pitch by entering two spaces, a dash (-), once more space and then the tone. (Notepad++ and other text editors don't require manually entering two spaces)
• When removing pitches ensure the entire line is removed.

Editing Tone Delay/Length

• Tone Delay is marked as "TONE_DELAY=#". You can change the default number but it must be between 0 and 9999.
• The value for tone delay is in milliseconds.
• Tone Length is marked as "TONE_LENGTH=#". Modify it between 0 and 255.
• The value for tone length is in milliseconds.

Comments

• You can add your own personal comments in the song file.
• Insert a "#" and then your comment.
• Comments are not read by the compiler and are glossed over. Comments can be placed anywhere except directly after a pitch. (- GS2 #Hello = NOT ALLOWED)

Extra Information

Supported Pitches

85 total pitches + pause. Each tune button has 17 possible pitches.
The following table is organized as each of the possible pitches and tunes for each button. Starting from left (Green) to right (White).
Each button has a string "pitch" and a frequency in hertz which is related to that pitch.

# is represented as an "S". F#2 = FS2

Pitch	Frequency (Hz)	Pitch	Frequency (Hz)	Pitch	Frequency (Hz)	Pitch	Frequency (Hz)	Pitch	Frequency (Hz)
B0	31	E2	82	A3	220	D5	587	G6	1568
C1	33	F2	87	AS3	223	DS5	622	GS6	1661
CS1	35	FS2	93	B3	247	E5	659	A6	1760
D1	37	G2	98	C4	262	F5	698	AS6	1865
DS1	39	GS2	104	CS4	277	FS5	740	B6	1976
E1	41	A2	110	D4	294	G5	784	C7	2093
F1	44	AS2	117	DS4	311	GS5	831	CS7	2217
FS1	46	B2	123	E4	330	A5	880	D7	2349
G1	49	C3	131	F4	349	AS5	932	DS7	2489
GS1	52	CS3	139	FS4	370	B5	988	E7	2637
A1	55	D3	147	G4	392	C6	1047	F7	2794
AS1	58	DS3	156	GS4	415	CS6	1109	FS7	2960
B1	62	E3	165	A4	440	D6	1175	G7	3136
C2	65	F3	175	AS4	466	DS6	1245	GS7	3322
CS2	69	FS3	185	B4	494	E6	1319	A7	3520
D2	73	G3	196	C5	523	F6	1397	AS7	3729
DS2	78	GS3	208	CS5	554	FS6	1480	B7	3951

Troubleshooting

If you are having problems in TuneStudio2560 here are some suggestions.

Program Wont Start

If the program wont start then verify that the Arduino works and that the LCD is properly connected to the display.

Controls Do Not Work

Attempt to run the unit testing on TuneStudio2560 using Unity. (VS Code Command: PlatformIO: Test).
Unit testing will go step by step to check all the hardware and ensure it is working.

Program is Slow

Open the project in PlatformIO and ensure that the #DEBUG and #PERF_METRIC macros are "false" and not "true".

SD Card Not Working

1. Reinsert the SD
2. Double check wiring
3. Make sure CS pin on program matches the CS pin on SD
4. Verify the card is working on a PC
5. Make sure format is FAT32

Crashes When Trying to Play Song

1. Open the microSD card on your computer and inspect the song file. The song file should be properly formatted (2 spaces before each "-" a space and then a tone).
2. Ensure that the TONE_DELAY and TONE_LENGTH are proper numbers and there are no spaces between the equal signs and the numbers to the right of the equal signs.
3. Ensure that all pitches in the Data are proper and are supported by TuneStudio2560.

---

End of User Guide.

For any questions contact me.

---