com.kontakt.sdk.android.ble.connection.ibeacon

Class IBeaconConnection

java.lang.Object

com.kontakt.sdk.android.ble.connection.ibeacon.IBeaconConnection

All Implemented Interfaces:

RemoteDeviceConnection<IBeaconDevice>

public class IBeaconConnection
extends java.lang.Object
implements RemoteDeviceConnection<IBeaconDevice>

IBeacon connection allows to establish connection with beacon by authorizing it with its password and changing iBeacon parameters.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	IBeaconConnection.ConnectionListener
static class	IBeaconConnection.State State enum describes all possible state that BeaconConnection may be in.
static interface	IBeaconConnection.WriteBatchListener<T> WriteBatchListener provides callback methods notifying about writing parameters batch to Beacon device.
static interface	IBeaconConnection.WriteListener WriteListener provides callbacks indicating whether Beacon characteristics manipulation ended successfully or failed.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR_AUTHENTICATION Error code informing that unexpected error has occured while attempting beacon authentication.
static int	ERROR_BATCH_WRITE_INTERVAL Error code informing that Batch write operation failed during Interval write.
static int	ERROR_BATCH_WRITE_MAJOR Error code informing that Batch write operation failed during Major write.
static int	ERROR_BATCH_WRITE_MINOR Error code informing that Batch write operation failed during Minor write.
static int	ERROR_BATCH_WRITE_PROXIMITY_UUID Error code informing that Batch write operation failed during Proximity UUID write.
static int	ERROR_BATCH_WRITE_TX_POWER Error code informing that Batch write operation failed during Transmission Power write.
static int	ERROR_OVERWRITE_REQUEST Error code informing that error has occured during characteristic overwrite process.
static int	ERROR_SERVICES_DISCOVERY Error code informing that Beacon services discovery has failed.
static int	FAILURE_UNKNOWN_BEACON Failure code informing that BLE device was not recognised as kontakt.io Beacon.
static int	FAILURE_WRONG_PASSWORD Failure code informing that beacon was not authenticated because of wrong password.

Constructor Summary

Constructors

Constructor and Description
IBeaconConnection(android.content.Context context, IBeaconDevice beaconDevice, IBeaconConnection.ConnectionListener connectionListener)

Method Summary

Modifier and Type	Method and Description
void	acceptProfile(Profile profile, IBeaconConnection.WriteBatchListener<Profile> writeBatchListener) Accepts predefined profile (Profile) and changes parameters for Beacon.
void	applyConfig(Config config, IBeaconConnection.WriteBatchListener<Config> writeBatchListener) Applies pending configuration (Config) for Beacon.
void	close() Closes connection to the device.
boolean	connect() sends connection request to the device.
void	enableDfuMode(java.lang.String masterPassword, IBeaconConnection.WriteListener writeListener) Enables dfu mode.
void	enableNonConnectableMode(java.lang.String masterPassword, IBeaconConnection.WriteListener writeListener) Changes Beacon mode to non-connectable.
IBeaconDevice	getDevice() Gets remote device that the connection is established with.
boolean	isAuthenticated() Provides information whether the remote device has been authenticated.
boolean	isConnected() Provides information whether connection is established to the device.
void	overwriteAdvertisingInterval(long millis, IBeaconConnection.WriteListener writeListener) Changes Beacon advertising interval.
void	overwriteMajor(int value, IBeaconConnection.WriteListener writeListener) Changes Beacon major value.
void	overwriteMinor(int value, IBeaconConnection.WriteListener writeListener) Writes minor value.
void	overwriteModelName(java.lang.String newModelName, IBeaconConnection.WriteListener writeListener) Changes Beacon model name.
void	overwritePassword(java.lang.String newPassword, IBeaconConnection.WriteListener writeListener) Changes beacon password.
void	overwritePowerLevel(int powerLevel, IBeaconConnection.WriteListener writeListener) Changes Beacon power level.
void	overwriteProximity(java.util.UUID proximity, IBeaconConnection.WriteListener writeListener) Changes Beacon Proximity UUID value.
void	resetDevice(IBeaconConnection.WriteListener writeListener) Resets device so that connection is established once again.
void	restoreDefaultSettings(java.lang.String masterPassword, IBeaconConnection.WriteListener writeListener) Restores default Beacon settings.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERROR_SERVICES_DISCOVERY

public static final int ERROR_SERVICES_DISCOVERY

Error code informing that Beacon services discovery has failed.

See Also:

Constant Field Values

ERROR_OVERWRITE_REQUEST

public static final int ERROR_OVERWRITE_REQUEST

Error code informing that error has occured during characteristic overwrite process.

See Also:

Constant Field Values

ERROR_AUTHENTICATION

public static final int ERROR_AUTHENTICATION

Error code informing that unexpected error has occured while attempting beacon authentication.

See Also:

Constant Field Values

FAILURE_UNKNOWN_BEACON

public static final int FAILURE_UNKNOWN_BEACON

Failure code informing that BLE device was not recognised as kontakt.io Beacon.

See Also:

Constant Field Values

FAILURE_WRONG_PASSWORD

public static final int FAILURE_WRONG_PASSWORD

Failure code informing that beacon was not authenticated because of wrong password. When authentication failure occurs, beacon change its state to Non-connectable mode lasting about 20 minutes.

See Also:

Constant Field Values

ERROR_BATCH_WRITE_PROXIMITY_UUID

public static final int ERROR_BATCH_WRITE_PROXIMITY_UUID

Error code informing that Batch write operation failed during Proximity UUID write.

See Also:

Constant Field Values

ERROR_BATCH_WRITE_TX_POWER

public static final int ERROR_BATCH_WRITE_TX_POWER

Error code informing that Batch write operation failed during Transmission Power write.

See Also:

Constant Field Values

ERROR_BATCH_WRITE_MAJOR

public static final int ERROR_BATCH_WRITE_MAJOR

Error code informing that Batch write operation failed during Major write.

See Also:

Constant Field Values

ERROR_BATCH_WRITE_MINOR

public static final int ERROR_BATCH_WRITE_MINOR

Error code informing that Batch write operation failed during Minor write.

See Also:

Constant Field Values

ERROR_BATCH_WRITE_INTERVAL

public static final int ERROR_BATCH_WRITE_INTERVAL

Error code informing that Batch write operation failed during Interval write.

See Also:

Constant Field Values

Constructor Detail

IBeaconConnection

public IBeaconConnection(android.content.Context context,
                         IBeaconDevice beaconDevice,
                         IBeaconConnection.ConnectionListener connectionListener)

Method Detail

getDevice

public IBeaconDevice getDevice()

Description copied from interface: RemoteDeviceConnection

Gets remote device that the connection is established with.

Specified by:

getDevice in interface RemoteDeviceConnection<IBeaconDevice>

Returns:

the device

connect

public boolean connect()

Description copied from interface: RemoteDeviceConnection

sends connection request to the device.

Specified by:

connect in interface RemoteDeviceConnection<IBeaconDevice>

Returns:

the boolean

isConnected

public boolean isConnected()

Description copied from interface: RemoteDeviceConnection

Provides information whether connection is established to the device.

Specified by:

isConnected in interface RemoteDeviceConnection<IBeaconDevice>

Returns:

true if connection to the device is established

isAuthenticated

public boolean isAuthenticated()

Description copied from interface: RemoteDeviceConnection

Provides information whether the remote device has been authenticated.

Specified by:

isAuthenticated in interface RemoteDeviceConnection<IBeaconDevice>

Returns:

true if the remote device has been authenticated.

close

public void close()

Description copied from interface: RemoteDeviceConnection

Closes connection to the device.

Specified by:

close in interface RemoteDeviceConnection<IBeaconDevice>

applyConfig

public void applyConfig(Config config,
                        IBeaconConnection.WriteBatchListener<Config> writeBatchListener)

Applies pending configuration (Config) for Beacon.

* It is possible to encounter problems during batch (the Config in this case) write operation which result in launching error handle callback method. Once the write batch operation failes, the Write Batch Processor will attempt performing rollback write batch operation aiming at restoring original Beacon configuration. The rollback operation however may not succeed as well leaving Beacon device changed partially. Therefore it is strongly advisable to write batches in relatively close distance to Beacon device. Thus, the risk of leaving Beacon in unspecified state may be avoided. The method is synchronized.

Parameters:

config - the config

writeBatchListener - the write batch listener

acceptProfile

public void acceptProfile(Profile profile,
                          IBeaconConnection.WriteBatchListener<Profile> writeBatchListener)

Accepts predefined profile (Profile) and changes parameters for Beacon.

It is possible to encounter problems during batch (the Profile in this case) write operation which result in launching error handle callback method. Once the write batch operation failes, the Write Batch Processor will attempt performing rollback write batch operation aiming at restoring original Beacon configuration. The rollback operation however may not succeed as well leaving Beacon device changed partially. Therefore it is strongly advisable to write batches in relatively close distance to Beacon device. Thus, the risk of leaving Beacon in unspecified state may be avoided. The method is synchronized.

Parameters:

profile - the profile

writeBatchListener - the write batch listener

overwriteMinor

public void overwriteMinor(int value,
                           IBeaconConnection.WriteListener writeListener)

Writes minor value. The method is synchronized.

Parameters:

value - the value

writeListener - the write listener

enableNonConnectableMode

public void enableNonConnectableMode(java.lang.String masterPassword,
                                     IBeaconConnection.WriteListener writeListener)

Changes Beacon mode to non-connectable. During the non-connectable mode no connection can be established with the Beacon for about 20 minutes.

The non-connectable mode is also enabled when authentication failure occured because of providing wrong password.

Beacon Master Password can be obtained via REST Client. The result callback is invoked by WriteListener.

For more information concerning Beacon master password, see BeaconCredentials model (DeviceCredentials) The method is synchronized.

Parameters:

masterPassword - the beacon master password

writeListener - the write listener

overwriteMajor

public void overwriteMajor(int value,
                           IBeaconConnection.WriteListener writeListener)

Changes Beacon major value. The result callback is invoked by WriteListener. The method is synchronized.

Parameters:

value - new value

writeListener - the write listener

overwriteProximity

public void overwriteProximity(java.util.UUID proximity,
                               IBeaconConnection.WriteListener writeListener)

Changes Beacon Proximity UUID value. The result callback is invoked by WriteListener. The method is synchronized.

Parameters:

proximity - the proximity UUID

writeListener - the write listener

overwritePassword

public void overwritePassword(java.lang.String newPassword,
                              IBeaconConnection.WriteListener writeListener)

Changes beacon password. The password must be 4-byte long. For more information see kontakt.io Datasheet - version 2.0. The result callback is invoked by WriteListener. The method is synchronized.

Parameters:

newPassword - the new password

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0

overwriteModelName

public void overwriteModelName(java.lang.String newModelName,
                               IBeaconConnection.WriteListener writeListener)

Changes Beacon model name. The name should be no longer than sequence of 15 bytes (15 ASCII characters). For more information see kontakt.io Datasheet - version 2.0. The result callback is invoked by WriteListener. The method is synchronized.

Parameters:

newModelName - the new model name

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0

overwriteAdvertisingInterval

public void overwriteAdvertisingInterval(long millis,
                                         IBeaconConnection.WriteListener writeListener)

Changes Beacon advertising interval. The interval value is accepted in milliseconds and must be within [20 - 10240] ms range. The method is synchronized.

Parameters:

millis - the interval millis

writeListener - the write listener

overwritePowerLevel

public void overwritePowerLevel(int powerLevel,
                                IBeaconConnection.WriteListener writeListener)

Changes Beacon power level. The Power level is described by 8 levels where 0 is the lowest (default) and 7 is the highest. For more information see kontakt.io Datasheet - version 2.0.

The result callback is invoked by WriteListener. The method is synchronized.

Parameters:

powerLevel - the power level

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0.

resetDevice

public void resetDevice(IBeaconConnection.WriteListener writeListener)

Resets device so that connection is established once again.

For more information see kontakt.io Datasheet - version 2.0.

The result callback is invoked by WriteListener. The method is synchronized.

Parameters:

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0.

enableDfuMode

public void enableDfuMode(java.lang.String masterPassword,
                          IBeaconConnection.WriteListener writeListener)

Enables dfu mode. The method is synchronized.

Parameters:

masterPassword - the master password

writeListener - the write listener

restoreDefaultSettings

public void restoreDefaultSettings(java.lang.String masterPassword,
                                   IBeaconConnection.WriteListener writeListener)

Restores default Beacon settings. As an argument, 6-byte long Beacon master password must be provided. The master password can be obtained via API Client. The method is synchronized.

Parameters:

masterPassword - the master password

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0.