EN/Bindings/Cocoa

From Tinkerunity
Jump to: navigation, search


English Deutsch










Highlights of TinkerForge Cocoa Layer

Version 2.0, March 2013

Please Note: This is only a short overview. Please see the 'DOCUMENTATION' for an in-depth description of the Protocols and all Object Classes.

General

  • Makes your code significantly more readable, and using Bricklets much, much easier. For example, let us assume you want to read the status of pin 3 of an IO bricklet. Instead of writing io4_get_value(&myio4, &myMask) and then dicking around with the bits in myMask, in Cocoa you write [myIO4 valueForPin:3]
  • Exists as a wrapper on top of the normal C binding layer. You can still call all lower-level API by accessing the device struct through [myDevice device]
  • All Bricks and Bricklets are NSObjects
  • All Bricks and Bricklets have a common ancestor, TinkerDevice
  • The TinkerDevice class implements common methods for all devices, e.g. 'deviceName', 'description', 'uid' etc
  • TinkerDevices have a tree hierarchy so you can use similar devices with the same method, or even interchange them. For example, IO4 and IO16 use setPin:toValue. If you upgrade your IO4 to IO16, you need to change a single line in your code where the object is inited. No other changes required.
  • Since all TinkerDevices conform to NSObject, and have a root object (TinkerDevice) you can use them in NSArrays and fast enumerate them
  • Instead of callback hacks, TinkerObjects and TinkerIO use delegation objects and optional protocols to make you code clean


  • TinkerIO2, the cocoa object that implements the classic-C 'IPconection' is also an NSObject with accessor functions.
  • TinkerIO is set up to support delegate objects. That way, your app is automatically notified when a device is found, added, or removed. This beoces available when (if) API 2.0 rolls around with support for context data pointers for all callbacks
  • TinkerIO2 supports the TinkerIO Protocol out-of the box. If you set a delegate to a TinkerIO2 object, that object receives all notifications for conects, disconnects, added and removed bricks etc.
  • The layer comes with TinkerUtilities, a small library of convenience functions that makes conversion from bitmasks to values and back much, much simpler. Now you can use proper NSIndexSets for bit masks.


Specific

  • The LCD device tree has a screen emulation built in (with goto, write, writeln, scrolling and stuff) and is fully compatible with NSString
   the TDSampler tree allows you to use most input bricklets interchangeably (e.g. rotary poti, linear poti, ambient light sensor, IR distance sensor, etc). Method naming is harmonized - the position: methods accesses the processed value, and value: returns the unprocessed ('analog') values.
  • The TDRelay tree allows you to use different relay brickslets interchangeably (dual, quad), and adds some convenience functions (Toggle, setRelay:toStatus:)
  • The TDIO tree allows you to use different IO bricklets interchangeably (4, 16), and does away with 'ports'. Even better, it allows you change every single pin individually (set, read, configure, interrupt) without ever resorting to a mask
  • The TDIO and TDRelay trees provides Arrays object in which you can collect an arbitrary number of IO or Relay devices and treat them as one large device


How to use the cocoa layer

  • In your xcode project, add the C-Bindings (like you would when you use the classic C bindings). This adds all TinkerForge bindings to your project. You now can program your bricks the oldskool way. Don't.
  • Additionally, drag the 'Tinkerforge Cocoa' folder to your project. The cocoa layer sources are added to your project. The cocoa layer sits atop the C layer and is fully compatible with the C layer.
  • In your project, go to the App Delegate header fille
  • Add the following: #include "TinkerUtilities.h". This is the only include you need. All devices, connections and utilities are automagically accessible now.
  • Smile. Code cool stuff. Smile again.


Example:

Display the a message and updating current time on the 20x4 LCD. When done, quit nicely and turn off the lights. Create a new Project (non-core data, non-document) Add the C/C++ bindings to the project by downloading and then dragging the folder with all the '.c' and '.h' files on your project Add the cocoa layer (probably also a download) to your project the same way Edit the AppDelegate.h as follows - add the #include "TinkerUtilities.h" line - add the two instance variables 'theConnection' and 'theLCD'. your AppDelegate should look something like this:

#import <Cocoa/Cocoa.h>
#include "TinkerUtilities.h"

@interface myAppDelegate : NSObject <NSApplicationDelegate> {

    TinkerIO2 *theConnection; // IP connection to stack
    TDLCD20x4 *theLCD;

  NSWindow *window;

}

@property (assign) IBOutlet NSWindow *window;

@end

Now save and edit the AppDelegate.m file so it looks something this:


#import "myAppDelegate.h"

@implementation myAppDelegate

@synthesize window;


- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    // lets open an IP connection to the master brick
    theConnection = [[TinkerIO2 alloc] init]; 
    theLCD = [[TDLCD20x4 alloc] initWithUID:"xxx" connection:theConnection]; // IMPORTANT: CHANGE TO YOUR UID

    // connect to the devices so they become accessible
    [theConnection connectToHost:"localhost" port:4223];

    // switch LCD backlight on and present welcome screen
    [theLCD setBacklight:TRUE];
    [theLCD home]; // clear screen, goto 0,0; currently text autosync is on, so this will also clear screen
    [theLCD writeLnString:@"Welcome!"];
    [theLCD writeLnString:@""];
    [theLCD writeLnString:@"this is cf/x action!"];

    // go to sleep, and every second, update the time in the bottom
    [self performSelector:@selector(update) withObject:self afterDelay:1.0];
}	

- (void) update {

    CFGregorianDate currentDate = CFAbsoluteTimeGetGregorianDate(CFAbsoluteTimeGetCurrent(), CFTimeZoneCopySystem());
    NSString *time = [NSString stringWithFormat:@"%02d:%02d:%02.0f", currentDate.hour, 
                      currentDate.minute, currentDate.second];

    [theLCD moveToX:6 Y:3];
    [theLCD writeString:time];
    [self performSelector:@selector(update) withObject:self afterDelay:1.0];
}


- (void) applicationWillTerminate:(NSNotification *) aNotification {
    // say bye!
    [theLCD home];
    [theLCD writeString:@"bye..."];

    // turn off LCD backlight
    [theLCD setBacklight:FALSE];
}
@end


REMEMBER

You must run Brickv first to obtain the LCD's UID. Write it down and stick it in the code before you run it.

Copyright and stuff

Copyright © 2012, 2013 cf/x AG. All rights reserved.

http://www.cfxsoftware.com


Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:


The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software and its documentation.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Download

You can download the full bindings here: Media:Cocoa-Bindings-20.zip