login

online now

We have 84 guests and no members online

search

 

progamming guide



basic concepts

Before we get into programmings details, it might be useful to get an idea of how GinSing works and familiairize yourself with the hardware and software. These two sections will give you a firm footing ( and a development plan ) on how GinSing will work for your project.

how ginsing works

how the chip works

how the pc link works


support documentation

When referring to functions and what they do in the Ginsing library, you will find it useful to have the programming reference guide. You can download this document and refer to it frequently when writing your application. You can download the reference guide here:

programming reference guide



library

The library is constructed from a collection of header files ( .h ), and source files ( .cpp ), which can be found in your Arduino/libraries/GinSing folder. Due to the simplicity of the Arduino IDE these files are not easily viewed from within the Arduino editor itself. It is recommended that you navigate to this directory and use a conventional native editor on your PC to view these files.

Of most importance to understanding the functions of the interface is to understand the contents of the header files. These files contain the C++ classes and methods ( functions ) that comprise the system. Each header file contains a detailed description of its functional interface and usually is accompanied by a brief source code example. The library contains the following header files:


GinSing.h main system header file - main interface class ( the only header you need to include )
GinSingDefs.h all constants, variable types, enumerations, and definitons referred to by all the GinSing classes
GinSingPreset.h preset sound effects mode class and methods
GinSingPoly.h polyphonic ( musical instrument ) mode class and methods
GinSinVoice.h voice synthesis mode class and methods
GinSingSynth.h wave synthesizer mode class and methods
GinSingMaster.h master ( global ) class and methods
GinSingSerial.h serial interface class and methods
GinSingSerialDefs.h low level hardware specific serial interface definitions

For most header files there is a corresponding C++ source file ( .cpp ) where the code execution takes place. Most of the source code can be defined as a simple interface wrapper to the serial functions that send commands directly to the chip. See the functional overview for more information.



examples overview

The example programs are provided to give you a quick introduction to the features of GinSing and provide a template for building your own applications. The samples are ordered in such a way as to guide you through the system in an orderly fashion, building upon previous knowledge. For this reason we suggest you go through the example programs in the order recommended here. The example programs can be found in your Arduino/GinSing folder, and are directly loadable in the Arduino IDE via the File -> Sketchbook -> GinSing menu option.

1.welcome This program illustrates the basic concept of how to get the GinSing functionality into your own code. It does 4 iterations that go through the basic operating modes of the software in order ( poly , preset , voice , synth ) and run a built-in preview of each mode. Of most importance is the understanding of how the C++ class is created, what header file you need, and how to access the methods (functions) in each mode.
2.presetmode This program demonstrates the basics of preset sound effects mode. The chip contains 30+ built-in sound effects that are easy to trigger and fun to use. It illustrates how to access the preset class methods to cycle through all of the available preset sound effects and play them in order. It also demonstrates the concept of load, trigger, and release methods and utilizes only one of the two avaialble banks for playing effects.
3.polymode This program demonstrates the basics of polyphonic mode. In poly mode, the system is configured to create 6 identical voices that can be triggered simultaneously. In this example we create a simple note sequence and play using the musical scale in 3 part harmony. It demonstrates the basics of how to use GinSing as the basis for simple musical instruments.
4.voicemode This program demonstrates the basics of voice synthesis mode. In voice mode, all resources in the chip are allocated to perform synthetic speech. This example contains several small routines that demonstrate how to create simple phrases and how to control pitch, inflection, and speed.
5. synthmode This program demonstrates the basics of waveform synthesis mode. In synth mode, each of the 6 waveform generators can be patched in unique ways such as mixing and modulation to create complex waveforms. This example demonstrates some of the basic techniques used in waveform synthesis such as amplitude modulation, frequency modulation, frequency distortion, and more.


programming basics

In order to use the GinSing library in your Arduino application, you need only include the single header file GinSing.h, and create an instance of the C++ interface class. GinSing uses the C++ class abstraction as a simple way to organize all of its functions in a convenient manner. If you are new to C++ you can consider the operation of creating (instancing) the GinSing class as creating a portal to the functions that GinSing offers. In concrete terms, you need to have the two following lines in your code (outside of any execution loops).

#include 

GinSing GS;

void setup()
{
}

void loop()
{
}

Note that every Arduino program must define the setup() and loop() functions. In this example, we have created a static class called GS that we will use to reference the GinSing library functions. We could have just as easily called it myGinSing, or any other name you prefer. If all goes well this program won't do anything except compile, but we do now have access to the GinSing library.

Lets begin by acessing the initialization function to start up the system. Before any other calls are made to the library, we must call begin(). This function will initialize the serial connection to the chip and configure it in a default state. Likewise, when shutting down the system, we should call end() to quiet the chip and terminate the serial connection.This is typically done in  your setup() function anywhere its appropriate. As this function does not actually produce any sound it can be placed whereve it is convenient.

void setup()
{
GS.begin(recievePin, sendPin, overflowPin);
}

Note how we access the class to call the function. This allows the GinSing functions to exist in their own world (namespace) to avoid conflict with other code. The next step is to select the operating mode. The GinSing library operates in one of four modes, and you can switch from one mode to another mode at will; this allows you for example to switch from speaing a phrase to playing a musical melody instantly. Note that you cannot operate two modes simultaneously as each mode configures the hardware in a unique way. Lets begin by entering voice mode, and then have it say something:

void loop()
{
GSAllophone phrase[] = {_IE , _A , _M ,
   _BENDDN , _J, _I , _NE , _SE ,  _PITCHDN , _I , _PITCHDN , _NGE , _PA0 , _ENDPHRASE };

GS.getVoice().begin();
GS.getVoice().setNote ( C_2 );
GS.getVoice().speak ( phrase );
delay ( GS.getVoice().getMillis ( phrase ) + 500 );
}

As you can see, each mode has its own set of functions within the GinSing class. In fact, the GinSing class stores an internal pointer to the modes as their own classes, which allows you to access the class directly if you wish. Here is the same code that stores off the voice mode class and uses that directly instead:

void loop()
{
GSAllophone phrase[] = {_IE , _A , _M ,
    _BENDDN , _J, _I , _NE , _SE ,  _PITCHDN , _I , _PITCHDN , _NGE , _PA0 , _ENDPHRASE };


GingSingVoice *v = GS.getVoice();
v->begin();
v->setNote ( C_2 );
v->speak ( phrase );
delay ( v->getMillis ( phrase ) + 500 );
}

This is a more compact way to access the mode, and can be done for any of the other modes; you just need to store off the mode class in your code that is accessable when you need it. When you run this code, you will hear the voice speak "I am GinSing". Note the GSAllophone variable array contains a list of constants that are the speech fragments that make up the phrase - these (as will all constants and definitions) are defined in GinSingDefs.h. Note that this array can be as long as you like, but must be terminated with the _ENDPHRASE constant.

So from this we can see the command begin() is used to initialize whatever mode we wish to operate in. Each of the four modes all have this method defined in their class, and they all configure the chip for the upcoming functions calls that relate to that mode. The setNote() command is available in several modes and sets the frequency of the output to a musical note - in this case we are using C octave 2; the complete list of musical notes are available in GinSingDefs.h. The speak() command does the work of relaying the allophone list down to the chip to produce speech. In this example, we wait for the speech to complete ( plus 1/2 second ) before going on. There are many more functions available for controlling speech; take a look at GinSingVoice.h for more details.

At this point you should have a good enough understanding to take a look at the code that generates the sound demo you hear on our home page. Take a moment to examine this code as it demonstrates all of these basics and gives you a look into each of the modes available in the library.


I am GinSing demo code