README.md

iOS Port of the EasyTransfer Arduino Library

Easy serial communications between iOS devices and Arduinos via a RedPark serial cable.

While RedPark provides an SDK for using their cables for serial communications, it exposes a very primitive interface for sending and receiving bytes.

By porting Bill Porter's EasyTransfer Arduino Library, which originally was Arduino-to-Arduino communications only, to the iOS, we are now able to transfer structured data (namely C-structs) between the iOS device and the Arduino with very few lines of code.

Getting started

To use, just copy ArduinoEasyTransfer.{h,m} into your project and make sure that ArduinoEasyTransfer.m has been the application/library target's Compile Sources.

Declare C-structs wire format

These structs should be accessible from the Objective-C code as well as Arduino code, so it's convenient to stick them all in one header file. Let's call it data.h.

// data.h

struct XYCoordinates {
  int x;
  int y;
};

struct iDeviceToArduino {
  int foo;
  float bar;
  char quux;
  struct XYCoordinates coords;
};

struct ArduinoToIDevice {
  int x;
  int y;
}

Create instances of ArduinoEasyTransfer

Let's say we've define a class Foobar that handles serial communications. To handle events from the Redpark cable it must conform to the RscMgrDelegate protocol:

// Foobar.h

@interface Foobar : NSObject <RscMgrDelegate> {
  RscMgr *rscMgr;
  ArduinoEasyTransfer *txTransfer;
  ArduinoEasyTransfer *rxTransfer;
}
...
@end

You'll want to initialise these the following way:

// Foobar.m

#import "ArduinoEasyTransfer.h"
#import "RscMgr.h"
#import "data.h"

@implementation Foobar

-(id)init {
  if(self = [super init]) {
    rscMgr = [[RscMgr alloc] init];
    [rscMgr setDelegate:self];
    txTransfer = [[ArduinoEasyTransfer alloc] initWithSize:sizeof(typeof(struct iDeviceToArduino))];
    rxTransfer = [[ArduinoEasyTransfer alloc] initWithSize:sizeof(typeof(struct ArduinoToIDevice))];
  }
  return self;
}

...

@end

Sending data

// Foobar.m

  ...
  struct iDeviceToArduino txMessage = { 1, 2.0f, 'c', {10,20}};
  [txTransfer sendDataWith:rscMgr bytes:(void *)txMessage];
  ...

Receiving data

Just implement readBytesAvailable: so that we're told about any incoming data. We use EasyTransfer to make sense of it:

// Foobar.m

- (void)readBytesAvailable:(UInt32)numBytes {
  ...
  struct iDeviceToArduino rxMessage;
  ...
  while ([easyTransfer receiveDataFrom:rscMgr into:(void *)&rxMessage]) {
    // do something with rxMessage...
  }
  ...
}

Sending and receiving data on the Arduino side

Follow the code examples on EasyTransfer's home page.

In case of trouble...

No worries, just file an issue on GitHub. Better still, find out the issue and submit a pull request.

License

The MIT License (MIT)