EILLocationBuilder Class Reference

Inherits from NSObject
Declared in EILLocationBuilder.h
EILLocationBuilder.m

Overview

EILLocationBuilder is a builder object for creating EILLocation objects.

In order to construct a new location you need to:

  • set the shape of the location and its orientation
  • add details such as beacons, walls, doors on boundary segments

The shape of the location is defined by its boundary points. For example, consider a square defined by points (0,0), (0,5), (5,5), (5,0) along with its orientation with respect to the magnetic north.

[locationBuilder setLocationBoundaryPoints:@[
    [EILPoint pointWithX:0 y:0],
    [EILPoint pointWithX:0 y:5],
    [EILPoint pointWithX:5 y:5],
    [EILPoint pointWithX:5 y:0]]];

[locationBuilder setLocationOrientation:0];

Points that define shape of location also define its boundary segments. They are indexed in the same order as the points. There are following 4 segments: [(0,0), (0,5)], [(0,5), (5,5)], [(5,5), (5,0)], [(5,0), (0,0)].

The next step is to place beacons, doors on the boundary segments of the location:

[locationBuilder addBeaconWithIdentifier:@"63d4819e6a1d"
                  atBoundarySegmentIndex:0
                              inDistance:2
                                fromSide:EILLocationBuilderLeftSide];

Preparing shape of the location

– setLocationBoundaryPoints:

Adds a list of boundary points of location. Can be added clockwise or counter clockwise.

- (void)setLocationBoundaryPoints:(NSArray<EILPoint*> *)boundaryPoints

Parameters

boundaryPoints

List of boundary points that defines a location.

Declared In

EILLocationBuilder.h

– setLocationOrientation:

Sets the orientation of the room with respect to the magnetic north. Counted clockwise in degrees.

- (void)setLocationOrientation:(double)orientation

Parameters

orientation

Location orientation in degrees.

Declared In

EILLocationBuilder.h

Adding details of the location

– addBeaconWithIdentifier:atBoundarySegmentIndex:inDistance:fromSide:

Places a beacon on the boundary segment. Boundary segments were created in the same order as points were added.

- (void)addBeaconWithIdentifier:(NSString *)identifier atBoundarySegmentIndex:(NSUInteger)boundarySegmentIndex inDistance:(double)distance fromSide:(EILLocationBuilderSide)side

Parameters

identifier

Beacon identifier (MAC address or identifier).

boundarySegmentIndex

Index of the boundary segment.

distance

Distance from the beacon to the side of the boundary segment.

side

Side of the boundary segment as seen from inside of the location.

Declared In

EILLocationBuilder.h

– addBeaconWithIdentifier:withPosition:

Places a beacon in the location.

- (void)addBeaconWithIdentifier:(NSString *)identifier withPosition:(EILOrientedPoint *)position

Parameters

identifier

Beacon identifier (MAC address or identifier).

position

Coordinates of the beacon position.

Declared In

EILLocationBuilder.h

– addBeaconWithIdentifier:withPosition:andColor:

Places a beacon in the location.

- (void)addBeaconWithIdentifier:(NSString *)identifier withPosition:(EILOrientedPoint *)position andColor:(ESTColor)color

Parameters

identifier

Beacon identifier (MAC address or identifier).

position

Coordinates of the beacon position.

color

Color of the beacon.

Declared In

EILLocationBuilder.h

– addBeaconIdentifiedByMac:atBoundarySegmentIndex:inDistance:fromSide:

Places a beacon on the boundary segment. Boundary segments were created in the same order as points were added.

- (void)addBeaconIdentifiedByMac:(NSString *)macAddress atBoundarySegmentIndex:(NSUInteger)boundarySegmentIndex inDistance:(double)distance fromSide:(EILLocationBuilderSide)side

Parameters

macAddress

Beacon MAC address.

boundarySegmentIndex

Index of the boundary segment.

distance

Distance from the beacon to the side of the boundary segment.

side

Side of the boundary segment as seen from inside of the location.

This method is deprecated. Use addBeaconWithIdentifier:atBoundarySegmentIndex:inDistance:fromSide: instead.

Declared In

EILLocationBuilder.h

– addBeaconIdentifiedByMac:withPosition:

Places a beacon in the location.

- (void)addBeaconIdentifiedByMac:(NSString *)macAddress withPosition:(EILOrientedPoint *)position

Parameters

macAddress

Beacon MAC address.

position

Coordinates of the beacon position.

This method is deprecated. Use addBeaconWithIdentifier:withPosition: instead.

Declared In

EILLocationBuilder.h

– addBeaconIdentifiedByMac:withPosition:andColor:

Places a beacon in the location.

- (void)addBeaconIdentifiedByMac:(NSString *)macAddress withPosition:(EILOrientedPoint *)position andColor:(ESTColor)color

Parameters

macAddress

Beacon MAC address.

position

Coordinates of the beacon position.

color

Color of the beacon.

This method is deprecated. Use addBeaconWithIdentifier:withPosition:andColor: instead.

Declared In

EILLocationBuilder.h

– addDoorsWithLength:atBoundarySegmentIndex:inDistance:fromSide:

Places a door on the boundary segment. Boundary segments were created in the same order as points were added.

- (void)addDoorsWithLength:(double)length atBoundarySegmentIndex:(NSUInteger)boundarySegmentIndex inDistance:(double)distance fromSide:(EILLocationBuilderSide)side

Parameters

length

Length of the door.

boundarySegmentIndex

Index of the boundary segment.

distance

Distance from the door to the side of the boundary segment.

side

Side of the boundary segment as seen from inside of the location.

Declared In

EILLocationBuilder.h

– addWindowWithLength:atBoundarySegmentIndex:inDistance:fromSide:

Places a window on the boundary segment. Boundary segments were created in the same order as points were added.

- (void)addWindowWithLength:(double)length atBoundarySegmentIndex:(NSUInteger)boundarySegmentIndex inDistance:(double)distance fromSide:(EILLocationBuilderSide)side

Parameters

length

Length of the window.

boundarySegmentIndex

Index of the boundary segment.

distance

Distance from the window to the side of the boundary segment.

side

Side of the boundary segment as seen from inside of the location.

Declared In

EILLocationBuilder.h

– setLocationName:

Sets a name of the location. If not set EIL_LOCATION_DEFAULT_NAME is used.

- (void)setLocationName:(NSString *)locationName

Parameters

locationName

Name of the location.

Declared In

EILLocationBuilder.h

– setLocationCreationDate:

Sets a creation date of the location. If not set the current date is used.

- (void)setLocationCreationDate:(NSDate *)date

Parameters

date

Creation date.

Declared In

EILLocationBuilder.h

Building & Importing Location

– build

Builds a location.

- (nullable EILLocation *)build

Return Value

A valid location.

Declared In

EILLocationBuilder.h

+ parseFromJSON:

Parses JSON string representation of the location. You might have it from the older version of the app through “Export location code snippet”.

+ (nullable EILLocation *)parseFromJSON:(NSString *)json

Parameters

json

JSON encoded as a string representation of the location.

Return Value

Location object built based upon the JSON. Returns nil if location cannot be built.

Discussion

If location cannot be constructed based on JSON, an exception will be raised with explanation why it has happened.

Declared In

EILLocationBuilder.h