AppBeacon Method (CLIENT)

PLB Web Only, 9.9A

The AppBeacon method starts or stops specific beacon actions. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A CLIENT object that has been declared.

return

Optional. A Numeric Variable that returns the success or failure of the method.

id

Optional. A Character String Variable or string literal that specifies beacon region identifier provided by the PL/B program.

uuid

Optional. A Character String Variable or string literal that specifies the beacon region Uuid to match.

major

Optional. A Numeric Variable or decimal number that specifies a beacon region major number to match.

minor

Optional. A Numeric Variable or decimal number that specifies a beacon region minor number to match.

eventfreq

Optional. A Numeric Variable or decimal number that specifies the frequency in seconds between 'AppEventDidRangeBeaconsInRegion' events.

flags

Optional. A Numeric Variable or decimal number that specifies a bit mask value that controls the operations of this method.

Flags Affected: OVER, ZERO

Note the following:

1. Beacon support is only available when using a 'PlbWebCli' client for an Android or iOS device.

2. The beacon support is provided using the Cordova plugin found at the following URL:

https://github.com/petermetz/cordova-plugin-ibeacon

 

All beacon interactions and generated events are produced directly from this Cordova plugin package.

3. The ZERO flag is set if the {return} value is zero indicating that the method execution was successful.

4. The OVER flag is set if the value returned is too large to be stored into the {return} variable.

5. If {id} is not used, the default region identifier name of 'PlbWebCli' is used.

6. If {uuid} is not specified, the default UUID string of "14A09BE4-B6B3-444F-93C8-B8A47EFB0447" performs general actions for the mobile device only.

7. If {major} or {minor} are not specified, the default is to match for all beacon values available.

8. If {eventfreq} is not used, the default event frequency of one (1) second is used.

9. Some operations performed by the 'AppBeacon' method are based on the four (4) method parameters of {id}, {uuid}, {major}, and {minor} which specify a region(s) to either monitor or arange. These parameters are only needed when the {flags} parameter value is set to perform on of these actions:

 

    AppBeaconMonitorStart

    AppBeaconMonitorStop

    AppBeaconRangeStart

    AppBeaconRangeStop

 

The method parameters are used as follows:

 

a. The {id} parameter allows the PL/B program to specify a program name as an identifier for a beacon region. If this parameter is not specified, the default name of 'PlbWebCli' is used.

b. The {uuid} parameter allows the PL/B program to specify the unique uuid of a beacon region to find and perform the {flags} action against.

c. The {major} parameter allows the PL/B program to specify the major number of a beacon region(s) to find and perform the {flags} action against. If this parameter is not specified, the default is to match for all beacon major values available.

d. The {minor} parameter allows the PL/B program to specify the minor number of a beacon region(s) to find and perform the {flags} action against. If this parameter is not specified, the default is to match for all beacon minor values available.

 

10. The {eventfreq} parameter is only used to determine the frequency in seconds between beacon range events of the 'AppEventDidRangeBeaconsInRegion' event. If this parameter is not used, the default event frequency of one (1) second is used. When beacan range checking is turned on, the Cordova plugin continually generates and reports the range event. The {eventfreq} parameter can be used by the PL/B program to throttle the number of range events that are passed to the PL/B range checking logic in a specific time frame.

11. The {flags} parameter is numeric value where the combination of the bit mask values performs beacon action(s) for a beacon region. The {flags} action bit mask values are defined as follows:

 

Action	Value	Description
AppBeaconMonitorStart	0x1	Starts monitoring for a specific region identified by {id}, {uuid}, {major}, and {minor}.   This {flags} action can generate the following events:   AppEventDidStartMonitoringForRegion AppEventMonitoringDidFailForRegionWithError AppEventDidExitRegion AppEventDidEnterRegion
AppBeaconMonitorStop	0x2	Stop monitoring the a specific region identified by {id}, {uuid}, {major}, and {minor}.
AppBeaconRangeStart	0x4	Start range checking for a specific beacon region identified by {id}, {uuid}, {major}, and {minor}.   This {flags} action can generate the AppEventDidRangeBeaconsInRegion event.
AppEventDidRangeBeaconsInRegion	0x8	Stop range checking the specific beacon region identified by {id}, {uuid}, {major}, and {minor}.
AppBeaconBlueToothEnable	0x10	Enables Bluetooth on mobile device. (Android only)
AppBeaconBlueToothDisable	0x20	Disables Bluetooth on mobile device. (Android only)
AppBeaconRequestWhenInUseAuthorization	ox40	Request access to locate beacons when application is running. (iOS only)
AppBeaconRequestAlwaysAuthorization	0x80	Request access to locate beacons for application even when not running. (iOS only)
AppBeaconMonitorStopAll	0x100	Stop monitoring all regions.
AppBeaconRangeStopAll	0x200	Stop range checking for all beacon regions.

 

12. Once a beacon is monitored or ranged, scanning is not canceled by a CHAIN operation. Only a beacon stop or stop all operation terminates the scanning.

13. The {return} value is either a zero (0) when the method executes successfully. Otherwise, the {return} value is an error value as follows:

 

Error	Value	Description
AppErrorNone	0	No error.
AppErrorNoCordovaSupport	1	Action not supported by Cordova.
AppErrorWithExtendedInfo	2	Error with extended information. See CLIENT method named 'AppExtendedError'.

 

14. The AppBeacon method actions implemented by the Cordova plugin cause various events to occur. The events documented for specific actions under the {flags} parameter must be registered in the PL/B program using the EVENTREGISTER instruction. The results of the beacon generated events are stored in the EVENTREGISTER ARG1 variable. The ARG1 beacon event data is returned as a JSON string for the data provided by the Cordova event operations and determined by vendor beacon settings. The event numbers used to register the beacon events using EVENTREGISTER are defined as follows:

 

Event	Value
AppEventDidStartMonitoringForRegion	121
AppEventDidRangeBeaconsInRegion	122
AppEventMonitoringDidFailForRegionWithError	123
AppEventDidExitRegion	124
AppEventDidEnterRegion	125
AppEventDidRangeBeaconsInRegion	126

 

The general meaning of JSON tags:

 

Tag	Value
accuracy	Estimated distance in meters to two (2) decimal places.
proximity	A string containing one of:   ProximityUnknown - Beacon proximity is unknown.   ProximityImmediate - Beacon proximity is half a meter or less.   ProximityNear - Beacon proximity is four (4_ meters of less.   ProximityFar - Beacon proximity is greater than four meters.
rssi	Received signal strength indication
tx	Indicates what the expected signal level should be when you are one meter away.

 

Sample Beacon event data is:

AppEventDidStartMonitoringForRegion

{

  "region": {

    "typeName": "BeaconRegion",

    "minor": 9770,

    "major": 16100,

    "identifier": "Mint",

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D"

  },

  "eventType": "didStartMonitoringForRegion"

}

AppEventDidRangeBeaconsInRegion

 

Sample JSON string for no beacons.

{

  "region": {

    "typeName": "BeaconRegion",

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D",

    "identifier": "Estimote"

    },

  "eventType": "didRangeBeaconsInRegion",

  "beacons": []

}

Android Client

 

Sample JSON string for 2 Beacons using Android.

{

  "eventType": "didRangeBeaconsInRegion",

  "region": {

    "identifier": "Estimote",

    "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",

    "typeName": "BeaconRegion"

  },

  "beacons": [{

    "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",

    "major": "47441",

    "minor": "40095",

    "proximity": "ProximityImmediate",

    "rssi": -51,

    "tx": -72,

    "accuracy": 0.030000

  },

  {

    "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",

    "major": "62676",

    "minor": "6136",

    "proximity": "ProximityImmediate",

    "rssi": -58,

    "tx": -72,

    "accuracy": 0.100000

  }]

}

IOS Client

 

Sample JSON string for 3 Beacons using iOS.

{

  "region": {

    "typeName": "BeaconRegion",

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D",

    "identifier": "Estimote"

  },

  "eventType": "didRangeBeaconsInRegion",

  "beacons": [{

     "minor": 6136,

    "rssi": -72,

    "major": 62676,

    "proximity": "ProximityNear",

    "accuracy": 1.150000,

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D"

  },

  {

    "minor": 40095,

    "rssi": -74,

    "major": 47441,

    "proximity": "ProximityNear",

    "accuracy": 1.200000,

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D"

  },

  {

    "minor": 9770,

    "rssi": -80,

    "major": 16100,

    "proximity": "ProximityNear",

    "accuracy": 2.340000,

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D"

  }]

}

AppEventMonitoringDidFailForRegionWithError

 

{

  "region": {

    "typeName": "BeaconRegion",

    "minor": 9770,

    "major": 16100,

    "identifier": "Mint",

    "uuid": "B9407F30-F5F8-466E-AFF9-25556B57FE6D"

  },

  "eventType": "monitoringDidFailForRegionWithError",

  "error": "Error Domain=kCLErrorDomain Code=4 \"(null)\""

}

AppEventDidExitRegion

 

{

  eventType": "didExitRegion",

  "region": {

    "identifier": "Mint",

    "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",

    "major": "16100",

    "minor": "9770",

    "typeName": "BeaconRegion"

  }

}

AppEventDidEnterRegion

 

{

  "eventType": "didEnterRegion",

  "region": {

    "identifier": "Mint",

    "uuid": "b9407f30-f5f8-466e-aff9-25556b57fe6d",

    "major": "16100",

    "minor": "9770",

    "typeName": "BeaconRegion"

  }

}

Example Code:

.

.Setup for beacon interaction

.

    Client.AppBeacon Giving Result:

                     Using *FLAGS=(AppBeaconRequestWhenInUseAuthorization + AppBeaconBlueToothEnable)

.

.Clear all beacon monitoring and ranging:

.

    Client.AppBeacon Giving Result:

                     Using *FLAGS=(AppBeaconMonitorStopAll + AppBeaconRangeStopAll)

.

.Monitor one beacon region:

.

    EventReg Client:

             AppEventDidStartMonitoringForRegion:

             Event2:

             ARG1=BeaconEventData

.

    EventReg Client:

             AppEventMonitoringDidFailForRegionWithError:

             Event2:

             ARG1=BeaconEventData

.

    EventReg Client:

             AppEventDidExitRegion:

             Event2:

             ARG1=BeaconEventData

.

   EventReg Client:

            AppEventDidEnterRegion:

            Event2:

            ARG1=BeaconEventData

.

    Client.AppBeacon Giving Result:

                     Using "Mint":

                     "B9407F30-F5F8-466E-AFF9-25556B57FE6D":

                     16100,9770:

                     *FLAGS=AppBeaconMonitorStart

.

.Range beacon regions based on uuid:

.

BeaconUUID Init "B9407F30-F5F8-466E-AFF9-25556B57FE6D"

.

    EventReg Client:

             AppEventDidRangeBeaconsInRegion:

             Event2:

             ARG1=BeaconEventData

.

    Client.AppBeacon Giving Result:

           Using "Estimote":

           BeaconUUID:

           *FLAGS=AppBeaconRangeStart

See Also: CLIENT, Client Methods, Method Syntax