Package io.heraldprox.herald.sensor.ble

Class BLESensorConfiguration

  • public class BLESensorConfiguration
extends java.lang.Object
    Defines BLE sensor configuration data, e.g. service and characteristic UUIDs

    • Field Detail

      • serviceUUID

        @NonNull
public static java.util.UUID serviceUUID
        Service UUID for beacon service. This is a fixed UUID to enable iOS devices to find each other even in background mode. Android devices will need to find Apple devices first using the manufacturer code then discover services to identify actual beacons.
        - Service and characteristic UUIDs are V4 UUIDs that have been randomly generated and tested for uniqueness by conducting web searches to ensure it returns no results. Default UUID for HERALD is 428132af-4746-42d3-801e-4572d65bfd9b

        - Switch to 16-bit UUID by setting the value xxxx in base UUID 0000xxxx-0000-1000-8000-00805F9B34FB

      • androidSignalCharacteristicUUID

        @NonNull
public static final java.util.UUID androidSignalCharacteristicUUID
        Signaling characteristic for controlling connection between peripheral and central, e.g. keep each other from suspend state
        - Characteristic UUID is randomly generated V4 UUIDs that has been tested for uniqueness by conducting web searches to ensure it returns no results.

      • iosSignalCharacteristicUUID

        @NonNull
public static final java.util.UUID iosSignalCharacteristicUUID
        Signaling characteristic for controlling connection between peripheral and central, e.g. keep each other from suspend state
        - Characteristic UUID is randomly generated V4 UUIDs that has been tested for uniqueness by conducting web searches to ensure it returns no results.

      • payloadCharacteristicUUID

        @NonNull
public static final java.util.UUID payloadCharacteristicUUID
        Primary payload characteristic (read) for distributing payload data from peripheral to central, e.g. identity data
        - Characteristic UUID is randomly generated V4 UUIDs that has been tested for uniqueness by conducting web searches to ensure it returns no results.

      • interopOpenTraceEnabled

        public static boolean interopOpenTraceEnabled
        OpenTrace service UUID, characteristic UUID, and manufacturer ID
        - Enables capture of OpenTrace payloads, e.g. for transition to HERALD
        - HERALD will discover devices advertising OpenTrace service UUID (can be the same as HERALD service UUID)
        - HERALD will search for OpenTrace characteristic, write payload of self to target, read payload from target, and capture payload written to self by target.
        - HERALD will read/write payload from/to OpenTrace at regular intervals if update time interval is not .never. Tests have confirmed that using this feature, instead of relying solely on OpenTrace advert updates on idle Android and iOS devices offers more regular measurements for OpenTrace.
        - OpenTrace payloads will be reported via SensorDelegate:didRead where the payload has type LegacyPayloadData, and service will be the OpenTrace characteristic UUID.
        - Set interopOpenTraceEnabled = false to disable feature

      • interopOpenTraceServiceUUID

        @NonNull
public static java.util.UUID interopOpenTraceServiceUUID

      • interopOpenTracePayloadCharacteristicUUID

        @NonNull
public static java.util.UUID interopOpenTracePayloadCharacteristicUUID

      • interopOpenTraceManufacturerId

        public static int interopOpenTraceManufacturerId

      • interopOpenTracePayloadDataUpdateTimeInterval

        @NonNull
public static TimeInterval interopOpenTracePayloadDataUpdateTimeInterval

      • interopAdvertBasedProtocolEnabled

        public static boolean interopAdvertBasedProtocolEnabled
        Advert based protocol service UUID, service data key
        - Enable capture of advert based protocol payloads, e.g. for transition to HERALD
        - HERALD will discover devices advertising protocol service UUID (can be the same as HERALD service UUID)
        - HERALD will parse service data to read payload from target
        - Protocol payloads will be reported via SensorDelegate:didRead where the payload has type LegacyPayloadData, and service will be the protocol service UUID.
        - Set interopAdvertBasedProtocolEnabled = false to disable feature
        - Scan for 16-bit service UUID by setting the value xxxx in base UUID 0000xxxx-0000-1000-8000-00805F9B34FB

      • interopAdvertBasedProtocolServiceUUID

        @NonNull
public static java.util.UUID interopAdvertBasedProtocolServiceUUID

      • interopAdvertBasedProtocolServiceDataKey

        @NonNull
public static Data interopAdvertBasedProtocolServiceDataKey

      • bluetoothGenericAccessServiceUUID

        @NonNull
public static final java.util.UUID bluetoothGenericAccessServiceUUID
        Standard Bluetooth service and characteristics These are all fixed UUID from the BLE standard. Standard Bluetooth Service UUID for Generic Access Service
        - Service UUID from BLE standard

      • bluetoothGenericAccessServiceDeviceNameCharacteristicUUID

        @NonNull
public static final java.util.UUID bluetoothGenericAccessServiceDeviceNameCharacteristicUUID
        Standard Bluetooth Characteristic UUID for Generic Access Service : Device Name
        - Characteristic UUID from BLE standard

      • bluetoothGenericAccessServiceAppearanceCharacteristicUUID

        @NonNull
public static final java.util.UUID bluetoothGenericAccessServiceAppearanceCharacteristicUUID
        Standard Bluetooth Characteristic UUID for Generic Access Service : Device Name
        - Characteristic UUID from BLE standard

      • bluetoothDeviceInformationServiceUUID

        @NonNull
public static final java.util.UUID bluetoothDeviceInformationServiceUUID
        Standard Bluetooth Service UUID for Device Information Service
        - Service UUID from BLE standard

      • bluetoothDeviceInformationServiceModelCharacteristicUUID

        @NonNull
public static final java.util.UUID bluetoothDeviceInformationServiceModelCharacteristicUUID
        Standard Bluetooth Characteristic UUID for Device Information Service : Model
        - Characteristic UUID from BLE standard

      • bluetoothDeviceInformationServiceManufacturerCharacteristicUUID

        @NonNull
public static final java.util.UUID bluetoothDeviceInformationServiceManufacturerCharacteristicUUID
        Standard Bluetooth Characteristic UUID for Device Information Service : Manufacturer
        - Characteristic UUID from BLE standard

      • bluetoothDeviceInformationServiceTxPowerCharacteristicUUID

        @NonNull
public static final java.util.UUID bluetoothDeviceInformationServiceTxPowerCharacteristicUUID
        Standard Bluetooth Characteristic UUID for Device Information Service : TX Power
        - Characteristic UUID from BLE standard

      • manufacturerIdForSensor

        public static final int manufacturerIdForSensor
        Manufacturer data is being used on Android to store pseudo device address
        - Pending update to dedicated ID
        See Also:
        Constant Field Values

      • manufacturerIdForApple

        public static final int manufacturerIdForApple
        BLE advert manufacturer ID for Apple, for scanning of background iOS devices
        See Also:
        Constant Field Values

      • signalCharacteristicActionWritePayload

        public static final byte signalCharacteristicActionWritePayload
        Signal characteristic action code for write payload, expect 1 byte action code followed by 2 byte little-endian Int16 integer value for payload data length, then payload data
        See Also:
        Constant Field Values

      • signalCharacteristicActionWriteRSSI

        public static final byte signalCharacteristicActionWriteRSSI
        Signal characteristic action code for write RSSI, expect 1 byte action code followed by 4 byte little-endian Int32 integer value for RSSI value
        See Also:
        Constant Field Values

      • signalCharacteristicActionWritePayloadSharing

        public static final byte signalCharacteristicActionWritePayloadSharing
        Signal characteristic action code for write payload, expect 1 byte action code followed by 2 byte little-endian Int16 integer value for payload sharing data length, then payload sharing data
        See Also:
        Constant Field Values

      • signalCharacteristicActionWriteImmediate

        public static final byte signalCharacteristicActionWriteImmediate
        Arbitrary immediate write
        See Also:
        Constant Field Values

      • logLevel

        @NonNull
public static SensorLoggerLevel logLevel
        Log level for BLESensor

      • payloadDataUpdateTimeInterval

        @NonNull
public static TimeInterval payloadDataUpdateTimeInterval
        Payload update at regular intervals, in addition to default HERALD communication process.
        - Use this to enable regular payload reads according to app payload lifespan.
        - Set to .never to disable this function.
        - Payload updates are reported to SensorDelegate as didRead.
        - Setting take immediate effect, no need to restart BLESensor, can also be applied while BLESensor is active.

      • filterDuplicatePayloadData

        @NonNull
public static TimeInterval filterDuplicatePayloadData
        Filter duplicate payload data and suppress sensor(didRead:fromTarget) delegate calls
        - Set to .never to disable this feature
        - Set time interval N to filter duplicate payload data seen in last N seconds
        - Example : 60 means filter duplicates in last minute
        - Filters all occurrences of payload data from all targets

      • payloadSharingExpiryTimeInterval

        @NonNull
public static TimeInterval payloadSharingExpiryTimeInterval
        Expiry time for shared payloads, to ensure only recently seen payloads are shared

      • advertRefreshTimeInterval

        @NonNull
public static TimeInterval advertRefreshTimeInterval
        Advert refresh time interval

      • pseudoDeviceAddressRandomisation

        @NonNull
public static RandomSource pseudoDeviceAddressRandomisation
        Randomisation method for generating the pseudo device addresses, see PseudoDeviceAddress and RandomSource for details.
        - Set to NonBlockingSecureRandom for reliable continuous operation, validated
        - Other methods will cause blocking after 4-8 hours and interrupt operation on idle devices
        - Blocking can also occur at app initialisation, advert refresh, and also impact system services

      • deviceIntrospectionEnabled

        public static boolean deviceIntrospectionEnabled
        Interrogate standard Bluetooth services to obtain device make/model data

      • deviceFilterTrainingEnabled

        public static boolean deviceFilterTrainingEnabled
        Enable device filter training
        - Use this to gather device make/model and advert messages
        - Generates "filter.csv" log file for analysis
        - Enable device introspection to obtain device make/model data
        - Performs device introspection even if the device does not advertise sensor services
        - Triggers update every minute for each device to gather sample advert data
        - Disables device filter feature patterns

      • deviceFilterFeaturePatterns

        @NonNull
public static java.lang.String[] deviceFilterFeaturePatterns
        Define device filtering rules based on message patterns
        - Avoids connections to devices that cannot host sensor services
        - Matches against every manufacturer specific data message (Hex format) in advert
        - Java regular expression patterns, case insensitive, find pattern anywhere in message
        - Remember to include ^ to match from start of message
        - Use deviceFilterTrainingEnabled in development environment to identify patterns

      • inertiaSensorEnabled

        public static boolean inertiaSensorEnabled
        Enable inertia sensor
        - Inertia sensor (accelerometer) measures acceleration in meters per second (m/s) along device X, Y and Z axis
        - Generates SensorDelegate:didVisit callbacks with InertiaLocationReference data
        - Set to false to disable sensor, and true value to enable sensor
        - This is used for automated capture of RSSI at different distances, where the didVisit data is used as markers

    • Constructor Detail

      • BLESensorConfiguration

        public BLESensorConfiguration()