Introduction

The Bleu SDK is composed of libbleu, a static library for iOS to communicate with Twocanoes' Bleu Stations. libbleu enables the following features:

  • Discovering Bleu Stations within range of an iOS device.
  • Reading and writing Bleu Station properties.
  • Easy provisioning of Bleu Stations by batch writing of properties.

Installation

libbleu is distributed as a compiled static library.

  1. Copy the files libbleu.a, TCSBleuStation.h, TCSBleuStationManager.h to your project. If you want to use the station browser, include TCSStationBrowserViewController.h
  2. In Xcode, select your build target, and click the Build Phases tab.
  3. In the Link Binary With Libraries build phase add:
    • libbleu.a
    • CoreBluetooth.framework
  4. Click the Build Settings tab
  5. Find the build setting for Library Search Paths
  6. Add a path to the directory containing your copy of libbleu.
  7. Under Build Setting, find the setting for Other Linker Flags
  8. Add the linker flag -ObjC to all build configurations.

Architectural Overview

The two classes for interacting with Bleu Stations are TCSBleuStationManager and TCSBleuStation.

Bleu Station Manager

The primary function of the Bleu Station manager is to discover Bleu Stations and create TCSBleuStation objects. The Bleu Station Manager interfaces with the Bluetooth stack on the iOS device to find Bleu Stations in range. Upon finding a station, it creates a TCSBleuStation object and passes a reference via the delegate call stationManager:didDiscoverStation:.

Bleu Station

The Bleu Station objects give read and write access to the properties of a Bleu Station. Read access via properties is available for convenience, but asynchronous calls with delegate callbacks are required for direct communication with the Blue Station.

Station Modes

Bleu Station can operate in different modes which affect how you discover and connect to them.

Admin/Deployment Mode

After a reset or firmware update the Bleu Station will be in Admin/Deployment mode. On power-on, the Station is in Admin mode. While it is in Admin mode, the Station is a connectable Bluetooth peripheral, but it is not a beacon. This is allows you to connect with Bleu Setup and make configuration changes. By default Admin mode lasts 30 seconds. After this time the station moves to Deployment mode. Once it has moved to Deployment mode it is not connectable or discoverable. The default for Admin mode is the first 30 seconds after power on. This can be altered in a few ways:

  • Changing the TCSBleuStationAdminTime property will change the number of seconds the station stays in Admin mode on startup.
  • Authenticating with the beacon prevents the Station from moving to Deployment mode. This allows you to stay connected as long as you need to change settings.
  • After you save changes with a beacon, the admin timer is reset and the countdown starts again.

For beacons with firmware 1.1 and later, you enable Admin mode by setting the TCSBleuStationAdminTime property to a value between 10 and 255, inclusive. This mode is not available for beacons with firmware prior to 1.1.

Test Mode

Test mode allows you to connect to the Station while it is broadcasting beacon proximity information. For stations with firmware 1.1.1 and later, you enable test mode by setting adminTimer to 0. Firmware versions prior to 1.1.1 allow only this mode.

Note: Putting your Station in test mode can be convenient during development, bit the station will not be as reliable for proximity updates.

Discovery

Stations in Admin Mode broadcast their availablity differently than in Test Mode. There are two ways to browse for Stations:

  • TCSStationScanModeAdmin will scan for Stations in Admin mode. Stations in Test mode will not appear.
  • TCSStationScanModeAdmin will scan for all BLE Bluetooth peripherals, including Stations in Test mode and Admin mode. It will also discover periphals that are not Bleu Stations. This is one of the reasons we recommend enabling Admin mode on the station and the associated discovery mode in libbleu. If you are in an area with lots of Bluetooth devices, this mode can become unusable.

Logging

Libbleu will look for a boolean (BOOL) in the user defaults with the key TCSLibbleuDebugLogging. If this is set to YES, additional logging will be sent to the console. Each object looks at this value at initialization time, so changing this value at runtime will only affect objects created after the change.