The gTar iOS SDK provides direct access to all hardware level functions of the gTar. You can use the SDK to recieve MIDI messages for user fret actions, and note triggers. You can also use the SDK to set LEDs and control the gTar display.
Download gTar SDK 1.0.5: GtarSDK_iOS_1_0_5.zip
This is a short tutorial showing how to get started using the gTar iOS SDK. This tutorial will go through setting up a basic iOS app to receive and send messages from the gTar.
First of all you'll need to download the most up to date version of the SDK: GtarSDK_iOS_1_0_5.zip
Save the files to a well known location on your computer and unzip the file. In the extracted folder you will find some reference documents in the /Documents folder and the actual SDK library in the /PublicProducts folder. Drag the /PublicProducts/Release-iphoneos/GtarController folder into your project. Make sure that you select the option to copy the files into the project. If you want to copy the files directly you'll need to change the path for Gtar.h in GtarController.h so it refers corretly.
Now that you have the files in the project select your main project in the project navigator and then in the editor view, under the header targets in the left-hand column, select the main project's target and navigate to the Build Phases tab.
Open up the Link Binary with Libraries section and click on the "+" in the bottom left. Choose the .a file that you added earlier and this will add the iPhone library to the project. This is the targetted library so using this will not work using a simulator. For now that's ok since it's hard to connect the gTar to th simulator, and we're working on better options for thefuture.
Next you need to add the CoreMIDI framework to your project. Click on the "+" again and choose the CoreMIDI framework from the ones made available by Apple. After you've done this you're all linked up, build the project just to make sure there are no issues.
Now we're ready to set up the GtarController. The way that the GtarController works is through an observer delegate. You can set up a view as a delegate as shown below:
@interface TestGtarAppViewController : UIViewController <GtarControllerObserver>
{
GtarController *m_pGtarController;
}
Now you need to allocate the GtarController and set the class as the observer delegate. You can do it in a convenient place like the viewDidLoad callback:
- (void)viewDidLoad
{
[super viewDidLoad];
m_pGtarController = [[GtarController alloc] init];
[m_pGtarController addObserver:self];
}
Now we have to add some of the delegate functions so that the controller doesn't puke:
- (void)gtarFretDown:(GtarPosition)position
{
// Triggers when a user pushes down a given fret
}
- (void)gtarFretUp:(GtarPosition)position
{
// Triggers when a given fret has been released
}
- (void)gtarNoteOn:(GtarPluck)pluck
{
// Triggered when a user plays a given note
}
- (void)gtarNoteOff:(GtarPosition)position
{
// Triggered when a given note is killed
}
- (void)gtarConnected
{
// Triggered when a gTar connection is detected
}
- (void)gtarDisconnected
{
// Triggered when an active gTar connection is terminated
}
So now when you run the app, when you connect the running app to the gTar the connection should be live. However, it won't do much! Lets add a button to light up some LEDs. Lets define an IBAction that will light up a random LED on the gTar when we hit a button. If you don't know how to set up a button/IBAction callback with xcode this is a good place to start.
-(IBAction)SetRandomLED:(id)sender
{
int randStr = arc4random() % 6;
int randFret = arc4random() % 16;
GtarLedColor randColor = GtarLedColorMake(arc4random() % 3, arc4random() % 3, arc4random() % 3);
[m_pGtarController turnOnLedAtPosition:GtarPositionMake(randFret, randStr) withColor:randColor];
}
Now everytime that action is triggered the gTar should light up a random LED position on the fretboard. you might notice that sometimes entire frets or strings will light up, this is because of the fact that turning on fret 0 on a given string will light up the entire string, and setting string 0 on a given fret will light up the entire fret. Sending an LED message with both string and fret set to 0 will result in the entire fretboard lighting up that color.
Now lets take a look at incoming messages from the gTar. We can fill out some of the delegate functions we set up before. Specifically, lets fill out gtarNoteOn and gtarNoteOff to light up / turn off LEDs when you play a specific note, or kill that note. This can be done as shown below:
- (void)gtarNoteOn:(GtarPluck)pluck
{
[m_pGtarController turnOnLedAtPosition:pluck.position withColor:GtarLedColorMake(3, 3, 3)];
}
- (void)gtarNoteOff:(GtarPosition)position
{
[m_pGtarController turnOffLedAtPosition:position];
}
As you can see the gTar iOS SDK is straight forward and extremely easy to use. We've done our best to keep the interface simple and uncluttered so you can worry about making great and amazing new applications for the gTar!
Found a bug or issue?