BLESensorConfiguration

public struct BLESensorConfiguration

Defines BLE sensor configuration data, e.g. service and characteristic UUIDs

  • 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.

    Declaration

    Swift

    public static var serviceUUID: CBUUID
  • 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.

    Declaration

    Swift

    public static var androidSignalCharacteristicUUID: CBUUID
  • 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.

    Declaration

    Swift

    public static var iosSignalCharacteristicUUID: CBUUID
  • 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.

    Declaration

    Swift

    public static var payloadCharacteristicUUID: CBUUID
  • Manufacturer data is being used on Android to store pseudo device address

    • Pending update to dedicated ID

    Declaration

    Swift

    public static var manufacturerIdForSensor: UInt16
  • 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

    Declaration

    Swift

    public static var interopOpenTraceEnabled: Bool
  • Undocumented

    Declaration

    Swift

    public static var interopOpenTraceServiceUUID: CBUUID
  • Undocumented

    Declaration

    Swift

    public static var interopOpenTracePayloadCharacteristicUUID: CBUUID
  • Undocumented

    Declaration

    Swift

    public static var interopOpenTraceManufacturerId: UInt16
  • Undocumented

    Declaration

    Swift

    public static var interopOpenTracePayloadDataUpdateTimeInterval: TimeInterval
  • 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

    Declaration

    Swift

    public static var interopAdvertBasedProtocolEnabled: Bool
  • Undocumented

    Declaration

    Swift

    public static var interopAdvertBasedProtocolServiceUUID: CBUUID
  • Undocumented

    Declaration

    Swift

    public static var interopAdvertBasedProtocolServiceDataKey: CBUUID
  • 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

    Declaration

    Swift

    public static var signalCharacteristicActionWritePayload: UInt8
  • Signal characteristic action code for write RSSI, expect 1 byte action code followed by 4 byte little-endian Int32 integer value for RSSI value

    Declaration

    Swift

    public static var signalCharacteristicActionWriteRSSI: UInt8
  • 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

    Declaration

    Swift

    public static var signalCharacteristicActionWritePayloadSharing: UInt8
  • Signal characteristic action code for arbitrary immediate write

    Declaration

    Swift

    public static var signalCharacteristicActionWriteImmediate: UInt8
  • Time delay between notifications for subscribers.

    Declaration

    Swift

    public static var notificationDelay: DispatchTimeInterval
  • Time delay between advert restart

    Declaration

    Swift

    public static var advertRestartTimeInterval: TimeInterval
  • Maximum number of concurrent BLE connections

    Declaration

    Swift

    public static var concurrentConnectionQuota: Int
  • Advert refresh time interval on Android devices

    Declaration

    Swift

    public static var androidAdvertRefreshTimeInterval: TimeInterval
  • Herald internal connection expiry timeout

    Declaration

    Swift

    public static var connectionAttemptTimeout: TimeInterval
  • The amount of time after which a diary venue event will stay in the log file (may be shown in the UI as ‘pending’ before this limit)

    Declaration

    Swift

    public static var venueCheckInTimeLimit: TimeInterval
  • The amount of time after which a venue presence diary event will be said to have been finished

    Declaration

    Swift

    public static var venueCheckOutTimeLimit: TimeInterval
  • The default number of days to save venue diary visits for, set by preference of the user. May be nil (no limit) or 0 (don’t record anything, ever)

    Declaration

    Swift

    public static var venueDiaryDefaultRecordingDays: UInt8?
  • If sharing a venue diary (E.g. via email to contact tracers), the number of days by default to share. nil means all. 0 means none

    Declaration

    Swift

    public static var venueDiaryDefaultShareDays: UInt8?
  • If sharing a venue diary (E.g. via email to contact tracers), the email address to send the diary to by default when ‘share’ is clicked

    Declaration

    Swift

    public static var venueDiaryDefaultShareEmail: String?
  • Log level for BLESensor

    Declaration

    Swift

    public static var logLevel: SensorLoggerLevel
  • Mobility sensor for estimating range of travel without recording location

    • Use this for prioritising positive cases that may have spread the disease over significant distances
    • Enabling location permission also has the benefit of enabling awake on screen for iOS-iOS background detection
    • Set to nil to disable sensor, set to distance in metres to enable sensor for mobility sensing at given resolution.

    Declaration

    Swift

    public static var mobilitySensorEnabled: Distance?
  • 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.

    Declaration

    Swift

    public static var payloadDataUpdateTimeInterval: TimeInterval
  • 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

    Declaration

    Swift

    public static var filterDuplicatePayloadData: TimeInterval
  • Remove peripheral records that haven’t been updated for some time.

    • Herald aims to maintain a regular “connection” to all peripherals to gather precise proximity and duration data for all peripheral records.
    • A regular connection in this context means frequent data sampling that may or may not require an actual connection.
    • For example, RSSI measurements are taken from adverts, thus do not require an active connection; even the connection on iOS is just an illusion for ease of understanding.
    • A peripheral record stops updating if the device has gone out of range, therefore the record can be deleted to reduce workload.
    • Upper bound : Set this value to iOS Bluetooth address rotation period (roughly 15 minutes) to maximise continuity when devices go out of range, then return back in range (connection resume period = 15 mins max).
    • Lower bound : Set this value to Android scan-process period (roughly 2 minutes) to minimise workload, but iOS connection resume will be more reliant on re-discovery (connection resume period = 2 mins or more dependent on external factors).
    • iOS-iOS connections may resume beyond the set interval value if the addresses have not changed, due to other mechanisms in Herald.

    Declaration

    Swift

    public static var peripheralCleanInterval: TimeInterval
  • 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

    Declaration

    Swift

    public static var inertiaSensorEnabled: Bool