iOS Client


  • Platform: iOS 7
  • Architecture: ARMv7, ARMv7s

Getting the files:

  1. Create a new project in XCode.
  2. In your project folder, clone the repository recursively:
    • git clone --recursive SOD
    • This will clone SOD files and obj-c (as well as SocketRocket support files)
  3. In XCode, right click on the project in the file view and choose "Add Files to ..."
  4. Select the newly cloned SOD folder, and click Add.
  5. In your project target, add the following libraries if they don't already exist:
    • CFNetwork.framework
    • Foundation.framework
    • Security.framework
    • libicucore.dylib
  6. At this point, your project should build although SoD is not being imported yet.

Using SoD in your project:


  1. Add reference to SoD in your ViewController.m:
    • #import "SOD.h"
    • #import "SocketIOPacket.h" (optional, if you want to implement didReceiveEvent() and parse the raw data packete yourself, rather than use the provided event notifications)
  2. Create an instance of SOD:
    • @property (nonatomic, strong) SOD *SOD;
  3. To connect to the server, add (perhaps under viewDidLoad):
    • self.SOD = [[SOD alloc] initWithAddress:@"" andPort:3000];
    • IMPORTANT: Change the IP address to the IP address of your server.
  4. If your server is running, your device should connect and push orientation data automatically.

Note: If the device disconnects, it can reconnect by calling:

  • [self.SOD reconnectToServer];

Sending a request to server

There are four main types of requests sent to the server:

  1. Send information to server: These requests tell the server about the device.
    • sendDeviceInfoToServer (device height, width, type, etc.)
    • sendOrientation (angle the device is facing - use calibrateDeviceAngle to set current angle to 0)
    • setPairingState (device is switching to pairing mode)
    • tryPairWithID (device wants to pair with a person)
    • unpairDevice (device wants to unpair)
  2. Get information from server: These requests get information stored on the server.
    • getDevicesWithSelection (get a list of all devices in the selection, eg. "inView")
    • getAllTrackedPeoplewithCallBack (get a list of all people tracked by server)
  3. Send information to a device: These requests provide a selection for the server to determine which devices will receive the information ("all", "inView", etc.)
    • sendString (send a string to specified device or devices)
    • sendDictionary (send a dictionary to specified device or devices)
  4. Request information from a device
    • requestDataWithRequestName (ask for some data with "requestName", from all devices in selection, eg. "all", inView", etc.)

Handling events

When your device receives data, it raises an event. These events are sent by NSNotificationCenter, via defaultCenter. To handle these events, add a listener:

  • [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(stringReceivedHandler:) name:@"string" object:nil];

In the above example, we add a listener for the "string" event. Whenever another device or the server sends an event called "string" (eg. socket.emit("string", "some sample string") ), stringReceivedHandler is called.

Here is an example of a handler:

- (void)stringReceivedHandler: (NSNotification*) event
NSDictionary *theData = [[event userInfo] objectForKey:@"data"];
NSLog(@"String received: %@", [theData objectForKey:@"data"]);

When raising events with NSNotificationCenter, arguments are stored in userInfo, which is passed with the event. In the above example, theData is the dictionary received by the device. A typical dictionary received will contain three objects, ie. "name", "data", and "PID".

  • name: event name
  • data: the actual data sent
  • PID: message ID, used for sending back replies (acknowledgements)