-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathindex.html
More file actions
204 lines (151 loc) · 11.7 KB
/
Copy pathindex.html
File metadata and controls
204 lines (151 loc) · 11.7 KB
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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8' />
<meta http-equiv="X-UA-Compatible" content="chrome=1" />
<meta name="description" content="OpenBLE : Wabsite" />
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/my.css">
<title>OpenBLE</title>
</head>
<body>
<!-- HEADER -->
<div id="header_wrap" class="outer">
<header class="inner">
<a id="forkme_banner" href="https://github.com/OpenBLE/OpenBLE">View on GitHub</a>
<a class="apple_banner" href="https://itunes.apple.com/us/app/openble/id808685632?ls=1&mt=8"></a>
<h1 id="project_title">OpenBLE</h1>
<h2 id="project_tagline">BLE scanner and SPP chat for idevices</h2>
</header>
</div>
<!-- MAIN CONTENT -->
<div id="main_content_wrap" class="outer">
<section id="main_content" class="inner">
<h3>Description</h3>
<p>A simple iOS iPhone application and source code that demonstrates how to use the CoreBluetooth Framework to connect to a Bluetooth LE 'spp' peripheral. It lists bluetooth devices, connects and segues to a screen where you can send and receive data. It even has reconnect on loss of connection, and backgrounding support!<p>
<img style="width: 20%;" src="images/scanner.png"/><img style="width: 20%;" src="images/detail.png"/><img style="width: 20%;" src="images/notification.png"/>
<p>BUILD REQUIREMENTS:</p>
<ul>
<li>Xcode 5 or greater</li>
<li>iOS 7 SDK or greater</li>
</ul>
<p>RUNTIME REQUIREMENTS:<p>
<ul>
<li>iOS 6 or later - will not work on the simulator</li>
<li>Bluetooth LE Capable Device - iPhone 4s and later; iPad 3 and later; iPod Touch 5; iPad mini</li>
<li>Bluetooth LE Sensor - Currently supports the <a href="http://www.seeedstudio.com/depot/xadow-ble-slave-p-1546.html">Seeed Studio Xadow BLE device</a> as well as the <a href="http://redbearlab.com/bleshield/">Redbear</a> device and you can add support for other devices using the plist files.</li>
</ul>
<h3>Install it the hard way</h3>
<p>Download <a href="https://github.com/OpenBLE/OpenBLE">OpenBLE</a> and copy everything in /Classes into your xcode project. Or more preferrably install via <a href="http://beta.cocoapods.org/?q=">cocoapods</a>.</p>
<h3>Install it via Cocoapods</h3>
<p>Create a new xcode project, if you don't have an existing one or our example, then open a terminal and enter the directory where your .xcodeproj lives and type:</p>
<pre><code>sudo gem install cocoapods</code></pre>
<p>Now Cocoapods is installed in your system so you'll never have to do that again. Now you need a Podfile where your .xcodeproj lives. If you're running our example project you already have one! So just cd there and skip this step. If you've created a new project type:</p>
<pre><code>touch Podfile
echo -e "platform :ios, '6.0'\npod 'OpenBLE'" >> Podfile</code></pre>
<p>Now that cocoapods knows what to install for this project, type:</p>
<pre><code>pod install</code></pre>
<p>It should complete and tell you to <strong>utilize the new .xcworkspace from now on</strong>. Close your project if it was open, and open that new xcworkspace file. There's one thing you need to yet no matter what. You need to manually copy over the LE-Options.plist and LE-UUIDs.plist files from the Resources directory of OpenBLE. These files set up your scan preferences and UUIDs. By making them not part of the dependancy you can update them with new information and they wont get changed when you update OpenBLE.</p>
<h3>Use it</h3>
<p>There are several pieces to the OpenBLE project.
<ul>
<li>ScannerViewController and ScannerStoryboard</li>
<li>LeDiscovery class</li>
<li>LeDataService class</li>
</ul>
<h4>ScannerViewController and ScannerStoryboard</h4>
<p>With these two files we've attempted to make a reference implementation to get a Chooser interface in your own app with almost no setup. Go to your target's General tab and set your Main Interface to ScannerStoryboard.storyboard, make sure to (re)name your storyboard to MainStoryboard and embed your initial View Controller in a Navigation Controller.
<img src="images/MainInterface.png"/>
<img src="images/embed.png"/>
<p>Now you can just run your app and you'll see the Chooser window and if you have BLE devices in range you'll see them! When you select a bluetooth device it will connect and segue to the initial View Controller of the MainStoryBoard. Nothing else is hooked up so nothing happens, but you're scanning for BLE devices! So let's make something happen.</p>
<p>In your View Controller:
<pre><code>#import "ScannerViewController.h"</code></pre>
<p>And then presumably in viewDidLoad, you can dig out the peripheral you chose with:</p>
<pre><code>- (void)viewDidLoad
{
[super viewDidLoad];
// Do any additional setup after loading the view, typically from a nib.
UINavigationController *navController = (UINavigationController*)[self.navigationController presentingViewController];
ScannerViewController *rootController =(ScannerViewController*)[navController.viewControllers objectAtIndex:0];
CBPeripheral *peripheral = (CBPeripheral*)rootController.currentPeripheral;
}</code></pre>
<p> Note, if you don't hang on to your CBPeripheral object your connection will be terminated by the sytem.</p>
<h4>LeDataService class</h4>
<p>Now that you have a peripheral you'll want to send and receive data. Thus the second part of OpenBLE, LeDataService, is a reference implementation for serial BLE devices. First, we need to set ourselves as a delegate for the LeDataProtocol so we can receive updates. In your ViewController.h file:
<pre><code>#import <UIKit/UIKit.h>
#import "LeDataService.h"
#import "ScannerViewController.h"
@interface ViewController : UIViewController <LeDataProtocol>
@end</code></pre>
<p>Then, like we said above we need to hang on to our peripherals if we want to keep them. In this case LeDataService will hang on to our peripheral, but we need to hang on to it:</p>
<pre><code>#import "ViewController.h"
@interface ViewController (){
LeDataService *dataService;
}
@end
@implementation ViewController
....</code></pre>
<p>Now back in viewdidload where we found our peripheral, lets init our service and start it up</p>
<pre><code>dataService = [[LeDataService alloc] initWithPeripheral:peripheral delegate:self];
[dataService start];</code></pre>
<p>If startup was successful and the characteristics were found you'll get a serviceDidReceiveCharacteristicsFromService callback and you're ready to write. You'll get a didWriteFromService when complete and you can easily read from your device by registering for the serviceDidReceiveData callback:</p>
<pre><code>-(void)serviceDidReceiveCharacteristicsFromService:(LeDataService *)service
{
NSData* tosend=[@"Hello World" dataUsingEncoding:NSUTF8StringEncoding];
[dataService write:tosend];
}
-(void)didWriteFromService:(LeDataService *)service withError:(NSError *)error
{
NSLog(@"Data Sent!");
}
-(void)serviceDidReceiveData:(NSData *)data fromService:(LeDataService *)service
{
NSString* text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
NSLog(@"%@", text);
}</code></pre>
<p>Congrats, you're writing and reading from your device! Go on and start creating your app! For those who dont want to use the Storyboard, or want to know whats going on under the hood, continue below.</p>
<h4>LeDiscovery Class</h4>
<p>If you didnt want to use our storyboard as above, you'll need a quick walkthrough for discovery, too. If you did anything above, start over in a new project or if you trust yourself just undo everything. You need to set your class (probably a view controller) as a LeDiscoveryDelegate</p>
<pre><code>@interface ViewController : UIViewController <LeDiscoveryDelegate>
@end</code></pre>
<p>Create a discovery object, probably in your viewDidLoad, set yourself as its delegate, and start scanning for all devices (nil)</p>
<pre><code>[[LeDiscovery sharedInstance] setDiscoveryDelegate:self];
[[LeDiscovery sharedInstance] startScanningForUUIDString:nil];</code></pre>
<p>When the Discovery finds something it will tell you with th the discoveryDidRefresh delegate so set up that function:</p>
<pre><code>- (void) discoveryDidRefresh
{
//Connect to the first you find
NSArray *peripherals = [[LeDiscovery sharedInstance] foundPeripherals];
if([peripherals count] > 0){
CBPeripheral *peripheral = (CBPeripheral*)[peripherals objectAtIndex:0];
[[LeDiscovery sharedInstance] connectPeripheral:peripheral];
}
}</code></pre>
<p>You get a peripheralDidConnect delegate for a connect:</p>
<pre><code>- (void) peripheralDidConnect:(CBPeripheral *)peripheral
{
NSLog(@"Connected to: %@", [peripheral name]);
}
</code></pre>
<p>From there you've got a peripheral just like above! Like we mentioned there, make sure you save it or the system will disconnect the device and clear the memory. Take a look above at using LeDataService to make it easier to talk to your device!</p>
<h3>User Settings</h3>
<P>Adding new device UUIDs to the LE-UUIDs.plist should be self explanatory. There are read UUIDs, write UUIDs and service UUIDs, and at least one of each is necessary.<p>
<p>Options are a bit trickier, sadly. init-options is mapped to the CBCentralManager initWithDelegate options. connect-options is mapped to the CBCentralManager connectPeripheral options and scan-options is mapped to the CBCentralManager scanForPeripheralsWithServices options. Look up each of these 3 to see what options are available. Normally you'd enter they defined constant key, for instance, CBCentralManagerScanOptionAllowDuplicatesKey into the array. However since we're storing strings in a plist, we don't have access to that constant. What we do have access to the string it defines. So to enable CBCentralManagerScanOptionAllowDuplicatesKey we have to enter kCBScanOptionAllowDuplicates. To find the correct keys string you'll have to NSLog the key or look it up. Again we don't think this is ideal, so we're looking for feedback on better options.
<h3>Further reading</h3>
<ul>
<li><a href="https://developer.apple.com/library/ios/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/AboutCoreBluetooth/Introduction.html#//apple_ref/doc/uid/TP40013257-CH1-SW1">Apple Core Bluetooth Programming Guide<a></li>
<li><a href="https://developer.apple.com/wwdc/videos/index.php?id=703">WWDC Videos (sign in required)</a></li>
<li><a href="https://developer.apple.com/library/ios/samplecode/TemperatureSensor/Introduction/Intro.html">Apple Temperature Sensor Example</a></li>
</ul>
<h3><a name="support-or-contact" class="anchor" href="#support-or-contact"><span class="octicon octicon-link"></span></a>Support or Contact</h3>
<p>Use the github issues queue <a href="https://github.com/OpenBLE/OpenBLE/issues">https://github.com/OpenBLE/OpenBLE/issues</a> to report bugs or contribute code.</p>
</section>
</div>
<!-- FOOTER -->
<div id="footer_wrap" class="outer">
<footer class="inner">
<p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
</footer>
</div>
</body>
</html>