com.kontakt.sdk.android.ble.connection

Interface KontaktDeviceConnection

All Known Subinterfaces:

KontaktGatewayConnection

public interface KontaktDeviceConnection

KontaktDeviceConnection connection allows to establish connection with beacon.
Since firmware in version 4.0 device does not to have setup password, but below it still needs set password

All operation with device should be as quick as possible. You should not open connection and wait long time before taking any action. After doing job connection should be closed immediately

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	KontaktDeviceConnection.ConnectionListener

Method Summary

Modifier and Type	Method and Description
void	acceptProfile(Preset profile, WriteBatchListener<Preset> writeBatchListener) Accepts predefined profile (Preset) and changes parameters for Beacon.
void	applyConfig(Config config, WriteBatchListener<Config> writeBatchListener) Applies pending configuration (Config) for Device.
void	applySecureConfig(Config config, AuthToken token, WriteListener writeListener) Method for writing secure config offline.
void	applySecureConfig(java.lang.String encryptedConfig, WriteListener writeListener) Method for writing secure config.
void	authorize(AuthToken token, AuthorizationCallback callback) Authorizes with beacon.
void	close() Closes Beacon connection releases provided resources.
boolean	connect() Initializes connection to device provided in the KontaktDeviceConnection constructor.
boolean	connect(RemoteBluetoothDevice remoteBluetoothDevice) Initializes connection to given device.
void	enableDfuMode(java.lang.String masterPassword, WriteListener writeListener) Enables dfu mode.
void	enableNonConnectableMode(java.lang.String masterPassword, WriteListener writeListener) Changes Device mode to non-connectable.
void	executeSecureCommand(java.lang.String secureCommand, WriteListener writeListener) Executes Secure Command.
RemoteBluetoothDevice	getDevice() Gets beacon that the connection is established with.
boolean	isAuthenticated() Returns true if Beacon was successfully authenticated.
boolean	isClosed() Returns true if connection is closed.
boolean	isConnected() Returns true if Connection with Beacon is established.
void	overwriteAdvertisingInterval(long millis, WriteListener writeListener) Changes Beacon advertising interval.
void	overwriteInstanceId(java.lang.String instanceId, WriteListener writeListener) Overwrite instance id.
void	overwriteMajor(int value, WriteListener writeListener) Changes Beacon major value.
void	overwriteMinor(int value, WriteListener writeListener) Writes minor value.
void	overwriteModelName(java.lang.String newModelName, WriteListener writeListener) Changes Beacon model name.
void	overwriteNamespaceId(java.lang.String namespaceId, WriteListener writeListener) Overwrites namespace id.
void	overwritePassword(java.lang.String newPassword, WriteListener writeListener) Changes beacon password.
void	overwritePowerLevel(int powerLevel, WriteListener writeListener) Changes Beacon power level.
void	overwriteProximityUUID(java.util.UUID proximity, WriteListener writeListener) Changes Beacon Proximity UUID value.
void	overwriteUrl(java.lang.String newUrl, WriteListener writeListener) Overwrites url.
void	readAll(AuthToken token, ReadListener<Config> listener) Operation that returns beacon's current configuration wrapped in a Config object.
void	readLightSensor(ReadListener<java.lang.Integer> listener) Operation that returns current light sensor reading on a device.
void	readTime(ReadListener<Time> listener) Operation that returns current UTC time on a device.
void	resetDevice(WriteListener writeListener) Resets device so that connection is established once again.
void	restoreDefaultSettings(java.lang.String masterPassword, WriteListener writeListener) Restores default Beacon settings.
void	switchToDeviceProfile(DeviceProfile deviceProfile, WriteListener writeListener) Switch to device profile.
void	syncTime(WriteListener writeListener) Operation that synchronizes current UTC time with the beacon.
void	updateFirmware(Firmware firmware, byte[] fileBytes, KontaktCloud kontaktCloud, FirmwareUpdateListener firmwareUpdateListener) Method for initializing firmware update for Kontakt.io devices with secure profile (for now: Beacon PRO only).
void	updateFirmware(Firmware firmware, KontaktCloud kontaktCloud, FirmwareUpdateListener firmwareUpdateListener) Method for initializing firmware update for Kontakt.io devices with secure profile (for now: Beacon PRO only)

Method Detail

applyConfig

void applyConfig(Config config,
                 WriteBatchListener<Config> writeBatchListener)

Applies pending configuration (Config) for Device.
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 fails, 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.



Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

config - the config

writeBatchListener - the write batch listener

acceptProfile

void acceptProfile(Preset profile,
                   WriteBatchListener<Preset> writeBatchListener)

Accepts predefined profile (Preset) and changes parameters for Beacon.
It is possible to encounter problems during batch (the Preset 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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

profile - the profile

writeBatchListener - the write batch listener

overwriteMinor

void overwriteMinor(int value,
                    WriteListener writeListener)

Writes minor value. The method is synchronized.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

value - the value

writeListener - the write listener

enableNonConnectableMode

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

Changes Device mode to non-connectable. During the non-connectable mode no connection can be established with the Device for about 20 minutes.
The non-connectable mode is also enabled when authentication failure occured because of providing wrong password.
Device Master Password can be obtained via REST Client. The result callback is invoked by WriteListener.
For more information concerning Device master password, see Credentials model (Credentials)
The method is synchronized.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

masterPassword - the beacon master password

writeListener - the write listener

overwriteMajor

void overwriteMajor(int value,
                    WriteListener writeListener)

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

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

value - new value

writeListener - the write listener

overwriteProximityUUID

void overwriteProximityUUID(java.util.UUID proximity,
                            WriteListener writeListener)

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

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

proximity - the proximity UUID

writeListener - the write listener

overwritePassword

void overwritePassword(java.lang.String newPassword,
                       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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

newPassword - the new password

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0

overwriteModelName

void overwriteModelName(java.lang.String newModelName,
                        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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

newModelName - the new model name

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0

overwriteAdvertisingInterval

void overwriteAdvertisingInterval(long millis,
                                  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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

millis - the interval millis

writeListener - the write listener

overwritePowerLevel

void overwritePowerLevel(int powerLevel,
                         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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

powerLevel - the power level

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0.

switchToDeviceProfile

void switchToDeviceProfile(DeviceProfile deviceProfile,
                           WriteListener writeListener)

Switch to device profile.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

deviceProfile - the device profile

writeListener - the write listener

resetDevice

void resetDevice(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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0.

enableDfuMode

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

Enables dfu mode. The method is synchronized.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

masterPassword - the master password

writeListener - the write listener

overwriteUrl

void overwriteUrl(java.lang.String newUrl,
                  WriteListener writeListener)

Overwrites url. The method is synchronized.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

newUrl - the new url

writeListener - the write listener

overwriteNamespaceId

void overwriteNamespaceId(java.lang.String namespaceId,
                          WriteListener writeListener)

Overwrites namespace id. The method is synchronized.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

namespaceId - the namespace id

writeListener - the write listener

overwriteInstanceId

void overwriteInstanceId(java.lang.String instanceId,
                         WriteListener writeListener)

Overwrite instance id. The method is synchronized.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

instanceId - the instance id

writeListener - the write listener

restoreDefaultSettings

void restoreDefaultSettings(java.lang.String masterPassword,
                            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.

Throws IllegalOperationException if provided RemoteBluetoothDevice is in version 4.0 or higher

Parameters:

masterPassword - the master password

writeListener - the write listener

See Also:

kontakt.io Beacon Datasheet - version 2.0.

authorize

void authorize(AuthToken token,
               AuthorizationCallback callback)

Authorizes with beacon. Authorization is required before certain operations conducted on beacons with firmware 4.0 or higher and beacons pro.
These operations are:
- readTime(ReadListener)
- readLightSensor(ReadListener)

Parameters:

token - AuthToken instance required for authorization.

callback - Authorization result callback.

readAll

void readAll(AuthToken token,
             ReadListener<Config> listener)

Operation that returns beacon's current configuration wrapped in a Config object.
Successful read all operation is equal to successful authorization operation authorize(AuthToken, AuthorizationCallback).

Only available for beacons with firmware 4.0 or higher and beacons pro.

Parameters:

token - AuthToken instance.

listener - Read listener.

readTime

void readTime(ReadListener<Time> listener)

Operation that returns current UTC time on a device.
Only available for beacons pro.
Authorization is required before this operation. See authorize(AuthToken, AuthorizationCallback)

Parameters:

listener - Read listener

readLightSensor

void readLightSensor(ReadListener<java.lang.Integer> listener)

Operation that returns current light sensor reading on a device. Unit: 0 to 100 %
Only available for Beacons Pro with firmware 1.7 or higher.
Reading light sensor is based on characteristic notification so after using this method a sensor reading will be received continuously every 0.5 of a second. Authorization is required before this operation. See authorize(AuthToken, AuthorizationCallback)

Parameters:

listener - Read listener

applySecureConfig

void applySecureConfig(java.lang.String encryptedConfig,
                       WriteListener writeListener)

Method for writing secure config. Accessible for device with firmware 4.0 and above and Beacon Pro

Throws IllegalOperationException if provided device's firmware does not support this operation *

applySecureConfig

void applySecureConfig(Config config,
                       AuthToken token,
                       WriteListener writeListener)

Method for writing secure config offline. Accessible for devices with firmware 4.0 or higher and Beacon Pro
WARNING: This is an advanced feature that should not be used in normal situations. By applying offline secure configs you accept the fact that the beacon might be desynchronized with Kontakt Cloud.

Throws IllegalOperationException if provided device's firmware does not support this operation

Parameters:

config - Config that is about to be applied.

token - AuthToken token.

writeListener - Operation listener

executeSecureCommand

void executeSecureCommand(java.lang.String secureCommand,
                          WriteListener writeListener)

Executes Secure Command.

Parameters:

secureCommand - String representing secure command.

writeListener - Execution listener.

updateFirmware

void updateFirmware(Firmware firmware,
                    KontaktCloud kontaktCloud,
                    FirmwareUpdateListener firmwareUpdateListener)

Method for initializing firmware update for Kontakt.io devices with secure profile (for now: Beacon PRO only)

Parameters:

firmware - Firmware instance.

kontaktCloud - KontaktCloud instance. This is required for Beacon authorization and downloading firmware file.

firmwareUpdateListener - FirmwareUpdateListener instance. Listener that will report firmware update progress and errors.

updateFirmware

void updateFirmware(Firmware firmware,
                    byte[] fileBytes,
                    KontaktCloud kontaktCloud,
                    FirmwareUpdateListener firmwareUpdateListener)

Method for initializing firmware update for Kontakt.io devices with secure profile (for now: Beacon PRO only). This method should be used only uf you have pre-loaded byte array of valid firmware file.

Parameters:

firmware - Firmware instance.

fileBytes - Firmware file bytes.

kontaktCloud - KontaktCloud instance. This is required for Beacon authorization.

firmwareUpdateListener - FirmwareUpdateListener instance. Listener that will report firmware update progress and errors.

syncTime

void syncTime(WriteListener writeListener)

Operation that synchronizes current UTC time with the beacon.
Only available for beacons pro.
Authorization is required before this operation. See authorize(AuthToken, AuthorizationCallback)

Parameters:

writeListener - Write listener (extra will always be null in this case)

getDevice

RemoteBluetoothDevice getDevice()

Gets beacon that the connection is established with.

Returns:

the iBeacon device.

connect

boolean connect()

Initializes connection to device provided in the KontaktDeviceConnection constructor.

Returns:

true, if the connection attempt was initiated successfully

connect

boolean connect(RemoteBluetoothDevice remoteBluetoothDevice)

Initializes connection to given device.

Parameters:

remoteBluetoothDevice - device to connect to.

Returns:

true, if the connection attempt was initiated successfully.

close

void close()

Closes Beacon connection releases provided resources. The method is synchronized.

isConnected

boolean isConnected()

Returns true if Connection with Beacon is established. The method is synchronized.

Returns:

the boolean flag indicating whether connection is established.

isAuthenticated

boolean isAuthenticated()

Returns true if Beacon was successfully authenticated. The method is synchronized.

Returns:

the boolean flag indicating whether beacon was authenticated.

isClosed

boolean isClosed()

Returns true if connection is closed.

Returns:

the boolean flag indicating whether connection is closed.