Beacons on HSYCO App for iOS

WARNING! The Beacons functionality for iOS is experimental and subject to changes.

HSYCO App works with beacons to provide location awareness.

This can be used for example to trigger a specific command when a user enters or leaves an area, or to display a relevant information when the user approaches a location.

General Concept

Each beacon is identified with the following values:

• UUID: Universally Unique Identifier, which typically identifies a region
• Major: also called most significant value, used to distinguish beacons with the same UUID by dividing regions
• Minor: also called least significant value, used to divide regions even further

Beacons also have a Proximity property, which describes the distance between the beacon and the user's device. There are two modes of detecting beacons:

• monitoring: detects entering and exiting a region. This happens even when the app is closed or in background
• ranging: detects all the beacons currently in range, with their specific Proximity, which can have one of the following values: far, near, immediate, depending on the distance

HSYCO Implementation

HSYCO implements beacon detecting by using the values that identify a beacon to define regions as following:

• Area: defined by UUID. Beacons should be setup so that a device can only be inside one Area at a time. An Area could for example describe the region of a specific connection, like an office.
• Zones: divide Areas into smaller regions. Defined by UUID and Major. In the example above, a Zone could describe a room of the office.
• Beacons: a single beacon defined by UUID, Major and Minor. This could be used to define a sub-region of a room, like the a desk.

Each Beacon is defined in hsyco.ini and given a unique Location ID.

e.g. Here is an example of the configuration of a beacon in hsyco.ini

LocationBaseBeacon.17081 = ACFD165E-C0C0-11E3-9BBE-1A514932AC01,1,17081

iOS has a hard limit of 20 on the number of regions that can be monitored at the same time.

To work with this limitation, HSYCO App automatically decides which region to monitor, using the following logic:

• monitor Areas:
  • only if there are more than 20 Zones defined across all the enabled connections
  • only when the device is not inside an Area
  • a maximum of 20 Areas can be monitored
  • once an Area is entered, the App switches to monitor Zones
• monitor Zones
  • only if there are more than 20 beacons defined across all the enabled connections
  • a maximum of 20 Zones can be monitored
  • when the device exits all the Zones, the App switched to monitor Areas
• monitor Beacons
  • only if there are less than 20 beacons defined across all the enabled connections
  • useful for small applications, it gives the highest accuracy

Monitoring is used to detect entering and leaving regions. When the app is closed and an enter/exit event occurs, it will trigger ranging in background mode for a few seconds. This will in turn call the HSYCO Server LocationBeaconEvent, allowing logic to be applied. The Proximity of each beacon is saved locally on the device, so the LocationBeaconEvent will be triggered with the detected Proximity only when there's a variation. Ranging is always active for all defined beacons when the app is open (in foreground).

See the documentation of LocationBeaconEvent for more information: JavaScript Callback and Java Callback.

function LocationBeaconEvent(session, address, userid, zone, distance, background) : {
   messageLog("BEACON: " + address + ", " + userid + ", " + zone + "=" + distance + " (" + background + ")");
}

Configuring Beacons

Since no more than 20 Zones can be defined in an Area, working with more than that requires setting up the beacon identities in a specific way. Multiple beacons can have the same Zone identifier as long as the UUID is different.

So to cover large areas with a lot of Zones, 20 Zone identifiers can be repeated as long as they do not overlap, which means that at all times only one Zone with a specific identifier should be in range of a device.

Here's an example of how it could work:

In this example we will set the beacon's identities as follows:

• Beacon "B1"
  • UUID: ACFD165E-C0C0-11E3-9BBE-1A5149321001
  • Major: 101 (identifies the Area)
  • Minor: 1101 (identifies the Zone)
• Beacon "B2"
  • UUID: ACFD165E-C0C0-11E3-9BBE-1A5149321002
  • Major: 101 (identifies the Area)
  • Minor: 1101 (identifies the Zone)

...

• Beacon "B5"
  • UUID: ACFD165E-C0C0-11E3-9BBE-1A5149321005
  • Major: 101 (identifies the Area)
  • Minor: 1102 (identifies the Zone)

In hsyco.ini or Location Services under Settings:

LocationBaseBeacon.1001 = ACFD165E-C0C0-11E3-9BBE-1A5149321001,101,1101
LocationBaseBeacon.1002 = ACFD165E-C0C0-11E3-9BBE-1A5149321002,101,1101
LocationBaseBeacon.1005 = ACFD165E-C0C0-11E3-9BBE-1A5149321005,101,1102

and in Events:

function LocationBeaconEvent(session, address, userid, zone, distance, background) : {
  var beacon = "";
  switch (address) {
    case "1001":
      beacon = "B1";
      break;
    case "1002":
      beacon = "B2";
      break;
    case "1005":
      beacon = "B5";
      break;
  }

  // when a beacon is too far, distance will be "off"
  if (distance == "off") {
     messageLog("Beacon " + beacon + " is too far");
  } else {
     messageLog("Beacon " + beacon + " in zone " + zone + " has proximity: " + distance);
  }
}