Our SDK provides a wide range of both utility and client-facing features that will save time and make iBeacon development easier than ever. It's built purely on Apple Core Location and Core Bluetooth technologies and is 100% iBeacon compatible.
In addition to the Estimote SDK we've included a lot of examples to show you how to use our SDK in real scenarios. You should also check our utility app that can be found in the App Store.
To learn more, read the API section on our website. You can review the SDK documentation and check our Developer Portal to get the answers for the most common questions related to beacons and Estimote tools.
Estimote SDK 4.0 comes to you as a framework. To setup, you only need to include a single EstimoteSDK.framework file in your project to get started:
-
Drag and drop EstimoteSDK.framework file into your Xcode project. It will automatically show up in your project navigator and will be added to "Linked Frameworks and Libraries" section in project settings.
-
Estimote SDK depends on Apple's CoreLocation and CoreBlueooth frameworks as well as SystemConfiguration framework to handle Estimote Cloud API requests, so you should include them in your project too. When you add them to your project settings, it should look like on the screenshot below.
- That's it, congratulations and happy hacking!
The SDK requires iOS 7+, as it depends on the CoreLocation's support for iBeacon which was first introduced in iOS 7. Features of Estimote SDK are divided into two parts: Client and Utility.
Client part is dedicated to be used inside your publicly distributed applications featuring Estimote Beacons or Nearables integration. It helps you work with Apple iBeacon objects, adding useful functionality like filtering, ranged object limitation, or combining beacons from few regions into one callback.
Description of most important components are below:
ESTBeaconManager- Simple wrapper around Core Location's CLLocationManager class. It exposes API to range and monitor iBeacon devices with some additional options like sorting or filtering. It works with pure CLBeacon objects.ESTSecureBeaconManager- CLLocationManager wrapper dedicated to work with devices that are using Estimote Secure UUID. Similarily to ESTBeaconManager it allows to range and monitor secured devices as well as estimate their proximity.ESTNearableManager- Entry point to work with nearables. It allows to range and monitor stickers with given type or identifier in the similar manner to how it's done with iBeacon.ESTEddystoneManager- Entry point to work with Eddystones. Allows to discover Eddystone packets broadcasted by beacons.ESTDeviceManager- Use it to be up-to-date with current values of device's sensors (such as temperature) broadcasted in Estimote Telemetry packet.
When EstimoteTLM packet is enabled (see ESTSettingsEstimoteTLMEnable class), the Location Beacon broadcasts Estimote Telemetry packets. They contain information about current values read by beacon's sensors. Telemetry packet includes readings from:
- Motion sensor (3-axis acceleration & more)
- Ambient light sensor
- Temperature sensor
- Magnetometer sensor
- GPIO Ports
Usage
ESTDeviceManager *manager = [[ESTDeviceManager alloc] init];
ESTTelemetryNotificationTemperature *temperatureNotification = [[ESTTelemetryNotificationTemperature alloc] initWithNotificationBlock:^(ESTTelemetryInfoTemperature *temperature) {
NSLog(@"Current temperature: %@ C", temperature.temperatureInCelsius);
}];
[manager registerForTelemetryNotification:temperatureNotification];Utility was created to support apps that manage Estimote Beacons and Nearables. It provides beacon connectivity and configuration methods, so you can easily change settings like Proximity UUID, Major, Minor, Power Modes and much more. It also allows you to easily perform Over The Air firmware update. It works mainly with Core Bluetooth framework.
Connecting to device lets you change its settings (broadcasting power, advertising interval etc.). You have to be the beacon's owner in Estimote Cloud; every attempt to connect with a device not linked to your Estimote account will fail.
Connectivity packets are represented by ESTDeviceConnectable subclasses:
ESTDeviceLocationBeaconrepresents Estimote Location Beacon (4 Battery Beacon),ESTDeviceNearablerepresents Estimote Nearable.
Following steps are required to connect to a device:
-
Create
ESTDeviceManager, make sure your class conforms toESTDeviceManagerDelegateprotocol. -
Start discovery by calling
startDiscoveryWithFilter:with filter object. This can be eitherESTDeviceFilterLocationBeaconorESTDeviceFilterNearable. -
Method
deviceManager:didDiscoverDevices:provides discovered devices matching filter. -
Make sure your class conforms to
ESTDeviceConnectableDelegateprotocol and callconnecton discoveredESTDeviceConnectableobject. Now, the SDK verifies if the device is linked to account specified by AppID + AppToken pair, authorizes user, connects on the Bluetooth level and synchronizes settings by fetching their values from Cloud and writing to the device.
In order to connect to Estimote Proximity Beacon (1 Battery Beacon), use the SDK 3 API.
In SDK 4.0 each device setting is represented by an ESTSettingBase subclass. There are two ways of reading/writing settings - Convenience API and Advanced API.
These classes are wrappers around basic types (both primitives and objects) such as unsigned integer or NSString,
ESTSetting*classes are wrappers around values providing validation.ESTBeaconOperation*classes specify details used to read or write setting to the device.
To simply change a device setting you can use the Conveniece API tree.
Each device has one, here's an example of ESTDeviceLocationBeacon settings tree:
device
|- settings
|- iBeacon
|- proximityUUID
|- major
|- minor
...
|- estimote
|- enable
|- power
...
|- deviceInfo
|- color
|- name
...
...
To read/write s device setting value call readValueWithCompletion: or writeValue:completion: method on one of the tree's leaf.
Usage example
I have an Estimote Location Beacon and I want to turn iBeacon packet on, change its Major value to 500, and read its Proximity UUID.
[device.settings.iBeacon.enable writeValue:YES completion:^(ESTSettingIBeaconEnable *enableSetting, NSError *error) {
NSLog(@"iBeacon packet enabled");
}];
[device.settings.iBeacon.major writeValue:500 completion:^(ESTSettingIBeaconMajor *majorSetting, NSError *error) {
NSLog(@"Major set to 500");
}];
[device.settings.iBeacon.proximityUUID readValueWithCompletion:^(ESTSettingIBeaconProximityUUID *uuidSetting, NSError *error) {
NSLog(@"Proximity UUID is %@", [uuidSetting getValue]);
}];To speed up interacting with multiple settings at once you can use the Advanced API. Each setting has its own setting and operation classes pair.
- Setting classes are subclasses of
ESTSettingBaseand have their names constructed by concatenatingESTSetting+ SettingGroupName + SettingShortName (i.e. ESTSettingIBeaconMajor). They are wrappers around setting values (both primitive types and object types), they also provide value validation. - Operation classes are subclasses of
ESTSettingOperationand have their name constructed by concatenatingESTBeaconOperation(if it's a setting stored in the device memory, such as iBeacon Major) orESTCloudOperation(if it's a setting stored only in Cloud, such as DeviceInfo Name) + SettingGroupName + SettingShortName (i.e. ESTBeaconOperationIBeaconMajor or ESTCloudOperationDeviceInfoName).
Usage example
I have an Estimote Location Beacon and I want to turn iBeacon packet on, change its Major value to 200, read its Proximity UUID, perform many other operations and want to do this as fast as possible.
ESTSettingIBeaconEnable *enableSetting = [[ESTSettingIBeaconEnable alloc] initWithValue:YES];
ESTBeaconOperationIBeaconEnable *enableOperation = [ESTBeaconOperationIBeaconEnable writeOperationWithSetting:enableSetting completion:^(ESTSettingIBeaconEnable *setting, NSError *error)
NSLog(@"iBeacon packet enabled");
}];
unsigned short major = 200;
ESTSettingIBeaconMajor *majorSetting = [[ESTSettingIBeaconMajor alloc] initWithValue:major];
ESTBeaconOperationIBeaconMajor *majorOperation = [ESTBeaconOperationIBeaconMajor writeOperationWithSetting:majorSetting completion:^(ESTSettingIBeaconMajor *setting, NSError *error) {
NSLog(@"Major set to 200");
}];
ESTBeaconOperationIBeaconProximityUUID *uuidOperation = [ESTBeaconOperationIBeaconProximityUUID readValueWithCompletion:^(ESTSettingIBeaconProximityUUID *setting, NSError *error) {
NSLog(@"Proximity UUID is %@", [uuidSetting getValue]);
}];
...
[device.settings performOperations:enableOperation, majorOperation, uuidOperation, ..., nil];To perform bulk update operations on devices represented by ESTDeviceLocationBeacon class you should use the ESTLocationBeaconBulkUpdater class. Contrary to the ESTBulkUpdater it is not designed to be used as a singleton. ESTLocationBeaconBulkUpdater requires an array of of ESTLocationBeaconBulkUpdaterConfiguration objects to start. ESTLocationBeaconBulkUpdaterConfiguration consists of an identifier of the device which settings you want to modify and an array of ESTSettingOperation described in the Advanced API section. All bulk updater events will be delivered to the object assigned as it's delegate which should conform to ESTLocationBeaconBulkUpdaterDelegate protocol.
Usage example
I have an array of identifiers for my Location Beacons that should have their iBeacon packet on and major value set to 200.
NSMutableArray *bulkUpdateConfigurations = [NSMutableArray new];
NSArray *identifiers = @[@"identifier1", @"identifier2", @"identifier3"];
for (NSString *identifier in identifiers) {
ESTSettingIBeaconEnable *enableSetting = [[ESTSettingIBeaconEnable alloc] initWithValue:YES];
ESTBeaconOperationIBeaconEnable *enableOperation = [ESTBeaconOperationIBeaconEnable writeOperationWithSetting:enableSetting completion:^(ESTSettingIBeaconEnable *iBeaconEnableSetting, NSError *error) {
}];
unsigned short major = 200;
ESTSettingIBeaconMajor *majorSetting = [[ESTSettingIBeaconMajor alloc] initWithValue:major];
ESTBeaconOperationIBeaconMajor *majorOperation = [ESTBeaconOperationIBeaconMajor writeOperationWithSetting:majorSetting completion:^(ESTSettingIBeaconMajor *major, NSError *error) {
}];
ESTLocationBeaconBulkUpdateConfiguration *configuration = [[ESTLocationBeaconBulkUpdateConfiguration alloc] initWithDeviceIdentifier:identifier settingsOperations:@[enableOperation, majorOperation]];
[bulkUpdateConfigurations addObject:configuration];
}
[self.bulkUpdater startWithUpdateConfigurations:[NSArray arrayWithArray:bulkUpdateConfigurations]];To see what has changed in recent versions of Estimote SDK, see the CHANGELOG.