Multipeer Connectivity quick tutorial

Multipeer Connectivity is a new framework introduced in iOS 7. The framework provides support for discovering nearby devices using either Wi-Fi networks, peer-to-peer Wi-Fi, and Bluetooth personal area networks and communicating with those by sending data, streaming data and resources.

This tutorial will guide you through a very simple chatting app that connect nearby devices and chat to each other. Before coding the first line, let’s take a look at how multipeer connectivity works in iOS 7.

Consider two different users – Alice and Bob, who are using your app and are nearby each other. This is how these users would create a peer-to-peer session:

1.  Alice (the “advertise”) calls everyone around her: “Hey, I want to connect to you, anybody here?”.
2. Bob (the “browser”) listens to any call around him, searching for a nearby service to connect to.
3.  Once Bob finds Alice, he sends her a connection request. “Hello Alice, please connect to me!”.
4.  Alice accept or reject the request. If she accept the request, a peer-to-peer session is created between the two and they start to exchange data together.

The framework comes with an easy to use API to do all this, including some useful UI to advertise and browse nearby devices, the main classes in multipeer connectivity are:

•  MCPeerID: represents a peer in a session with custom display name.
•  MCSession: communicate between connected peer devices. You can create a session and invite other peers to join it, or you can join a session when invited by another peer.
•  MCNearbyServiceAdvertiser: tell nearby peers that you are willing to join sessions of a specified type.
•  MCNearbyServiceBrowser: search for nearby devices that are advertising.
•  MCAdvertiserAssistant: provide same functionality as MCNearbyServiceAdvertiser, along with a standard UI when invitation is sent. If you want to do additional programmatic logic and custom UI when sending invitation, use MCNearbyServiceAdvertiser instead.
•  MCBrowserViewController: provide standard UI that allows user to search and choose peers to invite.

GETTING STARTED

Because this app is about connecting devices and share data between them, so you must have at least 1 iOS device (along with 1 simulator) to test. Alternatively, you can create a new user on MAC, and run the project on 2 users, but you’ll have to switch user every now and then.

For simplicity,  we will use the standard UI Apple provided for searching and inviting: MCAdvertiserAssistant and MCBrowserViewController. Now open your XCode 5 and go to File/New/Project, choose “single view application” and click “Next”. Name your project “SimpleChat” or whatever you want and click “Next”, choose a Folder to save and click “Create”.

Compile and run the app, you should see a white blank screen:

Next, I’ll show you how to connect to nearby devices using standard UI. Add each part of this one by one and I’ll explain what exactly does each do.

1.  Add Required Framework

The first thing you have to do when using Multipeer Connectivity framework is, of cause, add it to your project. To add it, click on the “SimpleChat” project in the groups and files tree, switch to “Build Phases” tab and expand the “Link Binary with Libraries” section, click the ” + ” button and select Multipeer Connectivity framework.

2. Declares properties in ViewController.m

Open file ViewController.m add modify its interface so it looks like this:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

#import "ViewController.h" #import <MultipeerConnectivity/MultipeerConnectivity.h>   @interface ViewController ()<MCBrowserViewControllerDelegate, MCSessionDelegate, UITextFieldDelegate>   @property (nonatomic, strong) MCBrowserViewController *browserVC; @property (nonatomic, strong) MCAdvertiserAssistant *advertiser; @property (nonatomic, strong) MCSession *mySession; @property (nonatomic, strong) MCPeerID *myPeerID;   @property (nonatomic, strong) UIButton *browseButton; @property (nonatomic, strong) UITextView *textBox; @property (nonatomic, strong) UITextField *chatBox;   @end

This import the header you need to use Multipeer framework, and create instance variable you’ll need. The first 4 vars are needed for advertising, browsing device and inviting nearby device, the last 3 are chatting UI components.

3. Set up UI

Add a method to ViewController.m to setup UI components:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

- (void) setUpUI{     //  Setup the browse button     self.browserButton = [UIButton buttonWithType:UIButtonTypeSystem];     [self.browserButton setTitle:@"Browse" forState:UIControlStateNormal];     self.browserButton.frame = CGRectMake(130, 20, 60, 30);     [self.view addSubview:self.browserButton];       //  Setup TextBox     self.textBox = [[UITextView alloc] initWithFrame: CGRectMake(40, 150, 240, 270)];     self.textBox.editable = NO;     self.textBox.backgroundColor = [UIColor lightGrayColor];     [self.view addSubview: self.textBox];       //  Setup ChatBox     self.chatBox = [[UITextField alloc] initWithFrame: CGRectMake(40, 60, 240, 70)];     self.chatBox.backgroundColor = [UIColor lightGrayColor];     self.chatBox.returnKeyType = UIReturnKeySend;     [self.view addSubview:self.chatBox]; }

The “setup the browse button” part add a button to the view with a label “Browse”. The next 2 parts add a text box and a chat box which will be used to chat with nearby users.

Then, modify the viewDidLoad method:

1 2 3 4 5 6

- (void)viewDidLoad {     [super viewDidLoad];     // Do any additional setup after loading the view, typically from a nib.     [self setUpUI]; }

Compile and Run the project, you should see:

4.  Setup Multipeer components

Similarly, add a method called “setUpMultipeer” and call it in ViewController.m:

1 2 3 4 5 6 7 8 9 10 11 12 13

- (void) setUpMultipeer{     //  Setup peer ID     self.myPeerID = [[MCPeerID alloc] initWithDisplayName:[UIDevice currentDevice].name];       //  Setup session     self.mySession = [[MCSession alloc] initWithPeer:self.myPeerID];       //  Setup BrowserViewController     self.browserVC = [[MCBrowserViewController alloc] initWithServiceType:@"chat" session:self.mySession];       //  Setup Advertiser     self.advertiser = [[MCAdvertiserAssistant alloc] initWithServiceType:@"chat" discoveryInfo:nil session:self.mySession]; }

1 2 3 4 5 6 7

- (void)viewDidLoad {     [super viewDidLoad];     // Do any additional setup after loading the view, typically from a nib.     [self setUpUI];     [self setUpMultipeer]; }

[UIDevice currentDevice].name return the name of current Device (case simulator, the name is “iPhone simulator”),  so the first line create a new PeerID representing your device with a display name of your device.

The “setup session” line create a session with myPeerID as the local peer

The “setup browser view controller” create a new View Controller with Apple’s standard UI that handles searching for nearby devices and inviting them to session. The serviceType parameter is a short text string used to describe the  app’s networking protocol.  It should be in the same format as a  Bonjour service type: up to 15 characters long and valid characters  include ASCII lowercase letters, numbers, and the hyphen.  A short name that distinguishes itself from unrelated services is recommended; for  example, a text chat app made by ABC company could use the service type ”abc-txtchat”. Right now, just simply put it “chat”.

The final line create a new advertiser that handle telling other devices that you are willing to join them. The discoveryInfo is a NSDictionary containing info you want others to receive right when they found you, you can put it nil for now.

Now compile and run the project and try to tap the browse button, you’ll see … oops! Nothing happened, because no action was setup.

5. Setup some action.

Add an action method in your ViewController.m:

1 2 3

- (void) showBrowserVC{     [self presentViewController:self.browserVC animated:YES completion:nil]; }

and add this line in the setUpUI method to connect this action with the browser button:

1	[self.browserButton addTarget:self action:@selector(showBrowserVC) forControlEvents:UIControlEventTouchUpInside];

Now run the project once again, you can see that a browse view controller with Apple’s standard UI will be presented when you tap the browse button.

See the indicator spinning in the Searching cell? MCBrowserViewController automatically  search for nearby devices once it’s presented so you don’t have to do anything. There are 2 buttons “Done” and “Cancel” on top of the controller, purposed to dismiss it when you’re done with browsing and connecting to nearby devices or simply want to cancel the operation. To setup action when “Done” or “Cancel” button are tapped, implement the 2 method of the MCBrowserViewControllerProtocol (which you declared ViewController to adopt earlier):

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

- (void) dismissBrowserVC{     [self.browserVC dismissViewControllerAnimated:YES completion:nil]; }   #pragma marks MCBrowserViewControllerDelegate   // Notifies the delegate, when the user taps the done button - (void)browserViewControllerDidFinish:(MCBrowserViewController *)browserViewController{     [self dismissBrowserVC]; }   // Notifies delegate that the user taps the cancel button. - (void)browserViewControllerWasCancelled:(MCBrowserViewController *)browserViewController{     [self dismissBrowserVC]; }

You also need the set the bowser view controller’s delegate to ViewController, add this line to setUpMultipeer method:

1	self.browserVC.delegate = self;

Now when you tap the “Cancel” button, the browser view controller will dismiss and return to view controller.

6. Inviting and Connecting.

Connect your iPhone(or iPad) to your PC and run the project on both simulator and your connected device, try to browse for nearby peer on simulator. It would take about forever for your simulator to discover your iPhone because we’re still missing the “Alice calls everyone around her” part. Browser can only detect device that are advertising that they are willing to join. To do the advertising part, add this line to setUpMultipeer method, right after advertiser’s initialization:

1	[self.advertiser start]

This will get the advertiser to start advertising, quite simple huh? To stop advertising simply call method [self.advertiser stop], but you don’t need to do that in this simple app. Now run project on simulator and your iPhone and browse again, your simulator should detect your device:

Tap on the device you want to connect, your device should appear an alert message like this:

Accept it of cause, and that’s it! Your simulator and iPhone are now connected via MCSession.

Next, we’ll get to the sharing data part using MCSession and complete a very simple chat app.

1. Implement UITextFieldDelegate

After connecting complete, all data sharing process is executed by MCSession and MCPeerID. You can forget about MCAdvertiserAssistant and MCBrowserViewController now. MCSession provides several easy-to-use methods to send data to connected peers, the easiest to implement is

1	- (BOOL)sendData:(NSData *)data toPeers:(NSArray *)peerIDs withMode:(MCSessionSendDataMode)mode error:(NSError **)error;

This simply send a NSData object to peers in peerIDs array, with 2 modes: reliable (MCSessionSendDataReliable) and unreliable (MCSessionSendDataUnreliable). The reliable mode provide guaranteed reliable and in-order delivery with the cost of slow transfer while the other send data immediately without queuing, no guaranteed delivery. With the small and simple data (short text) in our app, it’s more efficient to choose the unreliable way to avoid traffic. Only consider use reliable mode when data is big like images.

Now imagine the chatting app, we’ll input our text to the chat box then tap ‘send’, the text box from both sender and receiver will appear that text along with sender’s display name. So let’s add a method:

1 2 3

- (void) sendText{   }

that we’ll modify later and implement the UITextFieldDelegate method:

1 2 3 4 5 6 7

#pragma marks UITextFieldDelegate   - (BOOL)textFieldShouldReturn:(UITextField *)textField{     [textField resignFirstResponder];     [self sendText];     return YES; }

and set the chat box delegate to view controller in setUpUI method:

1	self.chatBox.delegate = self;

so that when you tap the “send” button on the keyboard the method sendText would be called.

2. Handle Text

When user send or receive a message, the message is appear in text box with sender’s display name, so add a method appendText in ViewController.m:

1 2 3 4 5 6 7 8 9 10 11 12 13

- (void) receiveMessage: (NSString *) message fromPeer: (MCPeerID *) peer{     //  Create the final text to append     NSString *finalText;     if (peer == self.myPeerID) {         finalText = [NSString stringWithFormat:@"\nme: %@\n", message];     }     else{         finalText = [NSString stringWithFormat:@"\n%@: %@\n", peer.displayName, message];     }       //  Append text to text box     self.textBox.text = [self.textBox.text stringByAppendingString:finalText]; }

3. Sending data

Implement the sendText method we created earlier:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

- (void) sendText{     //  Retrieve text from chat box and clear chat box     NSString *message = self.chatBox.text;     self.chatBox.text = @"";       //  Convert text to NSData     NSData *data = [message dataUsingEncoding:NSUTF8StringEncoding];       //  Send data to connected peers     NSError *error;     [self.mySession sendData:data toPeers:[self.mySession connectedPeers] withMode:MCSessionSendDataUnreliable error:&error];       //  Append your own text to text box     [self receiveMessage: message fromPeer: self.myPeerID]; }

We retrieve text from chat box, clear chat box, convert text to NSData using a common encoding NSUTF8StringEncoding then send this data to all connected peers, then append the sent message to your own text box. [self.mySession connectedPeers] return a NSArray contain all connected peers to session, in some case you can set another array contain only specific peers you want to send data to.

4. Final Step: Receiving data – MCSessionDelegate

Until now, your app actually sent data and received data, but when receiving data your app does nothing. To get it in action, we need to implement the MCSessionDelegate’s methods.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

#pragma marks MCSessionDelegate // Remote peer changed state - (void)session:(MCSession *)session peer:(MCPeerID *)peerID didChangeState:(MCSessionState)state{   }   // Received data from remote peer - (void)session:(MCSession *)session didReceiveData:(NSData *)data fromPeer:(MCPeerID *)peerID{   }   // Received a byte stream from remote peer - (void)session:(MCSession *)session didReceiveStream:(NSInputStream *)stream withName:(NSString *)streamName fromPeer:(MCPeerID *)peerID{   }   // Start receiving a resource from remote peer - (void)session:(MCSession *)session didStartReceivingResourceWithName:(NSString *)resourceName fromPeer:(MCPeerID *)peerID withProgress:(NSProgress *)progress{   }   // Finished receiving a resource from remote peer and saved the content in a temporary location - the app is responsible for moving the file to a permanent location within its sandbox - (void)session:(MCSession *)session didFinishReceivingResourceWithName:(NSString *)resourceName fromPeer:(MCPeerID *)peerID atURL:(NSURL *)localURL withError:(NSError *)error{   } @end

All 5 methods are required in this protocol so we have to implement them all or we’ll receive complain from compiler. But the only method we’ll actually interact with is

- (void)session:(MCSession *)session didReceiveData:(NSData *)data fromPeer:(MCPeerID *)peerID

which is invoked every time you receive data sent from nearby peer.

1 2 3 4 5 6 7 8 9

- (void)session:(MCSession *)session didReceiveData:(NSData *)data fromPeer:(MCPeerID *)peerID{     //  Decode data back to NSString     NSString *message = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];       //  append message to text box on main thread     dispatch_async(dispatch_get_main_queue(),^{          [self receiveMessage: message fromPeer: peerID];     }); }

don’t forget to set the session’s delegate to view controller, add this line to method setUpMultipeer:

1	self.mySession.delegate = self;

Now your app is able to search for nearby devices, connect to them and sending messages to each other. Try chat to your self, and you’ll see something like this on both simulator and iPhone:

This is a very simple and far from “qualified” app you’ll create (you don’t even have to create a new single file), but it should give you a quick understanding of how the new framework works. For the full source code, click here. Hope you enjoy this tutorial.

Where to go from here?

So far it seems that we haven’t touched the MCNearbyServiceBrowser and MCNearbyServiceAdvertiser, but actually the two MCBrowserViewController and MCAdvertiserAssistant use them all the time behind the scene. Go ahead and try those lower api classes to set custom UI browser and additional programmatic logic through delegate’s protocols.