Share this article:

The IOS configuration APP, connecting to beacons and protecting your battery

The IOS configuration APP is downloadable from GitHub and you can easily compile the code and install it on an iPhone using Apple’s XCode package.

Before you use it let me explain a few things.  The Glimworm Beacons use Bluetooth Low Energy (BLE) which is a low power and lightweight version of Bluetooth, also referred to as Bluetooth 4.0.  In order to re-configure the beacons and upload your custom settings the IOS app makes a connection to the beacon “over the air” using BLE.

Before the connection is established and the configuration settings can be exchanged between the APP and the beacon there is a connection sequence which consists of :

  1. Discovery of the beacons by the APP
  2. The APP requests access to the beacon
  3. The beacon accepts or rejects the connection
  4. A connection is established and the beacon becomes un-discoverable to other BLE APPs
  5. The blue light on the beacon will burn to visually acknowledge the connection

Until step 4 when a connection is established the beacon is still discoverable by other APPs and if you have other BLE APPs installed on your MAC or other devices they may interfere with the sequence causing you to have to attempt the connection more than once in some cases.  Because BLE is such a lightweight and open protocol this is pretty much unavoidable but it should be nothing more than a minor irritation as you normally would not be changing the setting very often.

Warning : whilst connected to the beacon the battery is being drained and this will have an impact on the overall battery life.  tips :

  • Don’t change the settings too often on an installed beacon. This drains the battery
  • When we set up a batch we use one battery as the setup battery and then put a fresh one  in before we install them.
  • Don’t leave the connection open accidentally
  • Always pincode protect installed beacons as it protects both your battery from accidental draining and your settings from malicious alteration

Pincode protection

The connection sequence is altered when a beacon is pincode protected

  1. Discovery of the beacons by the APP
  2. The APP requests access to the beacon
  3. The beacon requires confirmation via a pincode
    3.1 IOS (not the APP) presents a PINCODE pairing window
    3.2 You enter the PINCODE, or press cancel
    3.3 The beacon receives the PINCODE
    3.4 The beacon accepts or rejects the connection
  4. A connection is established and the beacon becomes un-discoverable to other BLE APPs
  5. The blue light on the beacon lights up to visually acknowledge the connection

There are several things to take into account with a pincode protected beacon. Firstly and most obviously you must not forget the PINCODE as you won’t be able to access the beacon again.  Secondly the battery is protected because until step 4 you are not draining the battery significantly,  this is why we recommend putting a PINCODE on all production beacons.  Thirdly because the time between step 1 and step 4 is elongated there is a greater chance of other apps accidentally interfering with the connection sequence, therefore once PINCODE protected you can expect to have to attempt the connection a couple of times, however once you reach step 4 the beacon cannot be discovered and the connection is solid until you close it.

What does this look like in the app?

app_1

STEP 1 – DISCOVER BEACONS

If you switch on the configure beacons switch the APP will look for BLE devices in the surrounding area. The list is filtered on those devices that look like Glimworm Beacons but in some cases other BLE devices may look the same so the list can have mixed results that you have to ignore

Tips:

  • Glimworm beacons get a name starting with GB out of the box
app_1

STEP 2 – REQUEST ACCESS

When you find the beacon you want to set up in the list touch it to request a connection to the beacon

At this point a view with a spinning wheel will come up and you have to wait until a connection is established

Tips:

  • If you have to wait more than 20 secs the connection was most likely disturbed by another bluetooth program. Press cancel and try again. You can also close down Applications such as LightBlue which will be looking for the same beacons
app_1

STEP 3 – THE BEACON DECIDES IF YOU CAN HAVE ACCESS

If there is no PINCODE then you will see the setup screen next. However if you have a PINCODE you will be challenged for it

Tips :

  • At this point in the process you do not have an exclusive arrangement with the device and since it takes a few seconds for you you to enter your pincode it is likely that sometimes the process times out during step 3. If this happens just request a connection again to the beacon and try again. Don’t worry about your battery level – until the connection is made the beacon is still in low power mode.
app_1

STEP 4 and 5 – YOUR CONNECTION IS ESTABLISHED

You will see a blue light burning on the beacon – this is also visible through the casing as it is designed specifically to be semi-transparent

Tips :

  • Don’t stay connected for too long as you are running your battery down. If you have many beacons to set up we recommend using one battery for setting up all of the beacons and then putting a fresh one in each when you install them on location
app_1

STEP 6 – CONFUGURE AND CLOSE

The APP displays the current values. If in doubt you can hit the [reload] button to get them a 2nd time which is sometimes necessary. You can see the UUID, major, minor, advertisment rate and range of the beacons from this screen, [update] sends the new configuration to the beacon, [close] closes the connection

Tips :

  • [Auto] is a special button if you are setting up alot of beacons adding 1 to the minor and sets an automatic name for you. You can change this behaviour to suit you in the source code of the app

Downloading and Installing the App

You will need :

  • A Mac
  • Xcode installed with IOS7 SDK
  • An Iphone
  • A USB charging cable

STEP1 – Download from Github

The code is available on my GitHub page. You can download it by pressing the download as Zip button in the right hand menu area

STEP2 – Open the Project in Xcode

Open the downloaded files and double click on HiBeacons.xcworkspace

STEP3 – Connect your iPhone

Connect your phone using the USB cable and then open “organiser” and make sure it is recognised as a development device. You may need to click a button to set this up if you have not used this phone with Xcode before

STEP4 – Run

Select your phone and hit RUN


Wrap up

Hopefully you have now downloaded and installed the IOS setup app but if you have any questions or issues please either leave them on the github page as issues, or feel free to email us here at Glimworm Beacons using the contact form.