API: Return Temperature Readings from ThermoWorks WAND Blue Thermometer

Return temperature data from a connected ThermoWorks WAND Blue Bluetooth IR forehead thermometer.

In this article

Requirements

Kiosk Pro Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • Thermometers > Minimum RSSI Value (dBm) = recommended to start at default (-150)
  • iOS/iPadOS Permissions
    • Bluetooth - more on enabling specific iOS/iPadOS permissions here
  • Physical Hardware

Identifying a Specific Thermometer

Thermoworks WAND Blue thermometers do not have a built-in unique identifier for their hardware, which makes using multiple thermometers in a single space more challenging.

To address this limitation, we currently rely on a unique identifier returned by iOS/iPadOS when a new Bluetooth device is connected as a CBPeripheral object. This identfier is generated by the operating system and so will be different on different iPads for a single thermometer.

Apple does not guarantee this identifier will not change over time so if you are working on a project where more than one thermometer can potentially be in range, you will need to plan how to handle resetting the identifier if it changes. This could be handled automatically based on signal strength or manually in an admin screen. The app also includes a Minimum RSSI Value (dBm) setting to automatically filter discovery of thermometers that do not meet a specific signal strength threshold.

In our testing, this identifier has proven stable across multiple app deletion and reinstallation sessions, multiple thermometer power on-off sessions, multiple tablet power on-off sessions, and even after erasing the device and restoring it from a previous device backup. Resetting the device to factory settings and setting it up as a new device also reset this identifier. Discussions we found online suggest that using the device regularly can also help prevent the identifier from resetting.

Triggers via API Functions

Scan for Available Thermometers

This function triggers the app to scan for available Wand Blue thermometers via Bluetooth. It must also be called prior to any of the following calls to initiate the API.

Format 
kp_WBThermometerAPI_scanner_startDiscoveringThermometers(duration);
Parameters
  • duration - [string] the length of time to scan
    		•
    Triggers

    Kiosk Pro will immediately trigger kp_WBThermometerAPI_scanner_didStartDiscovering() or kp_WBThermometerAPI_scanner_didFailStartDiscovering with the state of scanning.

    When one or more thermometers are discovered, Kiosk Pro will trigger kp_WBThermometerAPI_scanner_didDiscoverThermometer or kp_WBThermometerAPI_scanner_didRejectDiscoveredThermometer.

    When the scanning duration is complete, Kiosk Pro will trigger When Scanning for a Thermometer Ends by Timeout.

    Stop Scanning for Thermometers

    This function triggers the app to stop scanning for available Wand Blue thermometers via Bluetooth.

    Format 
    kp_WBThermometerAPI_scanner_stopDiscoveringThermometers();
    Triggers Kiosk Pro will trigger kp_WBThermometerAPI_scanner_didStopDiscovering.

    Check Current Scanning State

    This function triggers a callback to return the current state of scanning for available thermometers.

    Format 
    kp_WBThermometerAPI_scanner_isDiscovering(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(isDiscovering);
    Callback return values
    • isDiscovering - [boolean integer] representing the current connection state. Possible values are:
      • 1 - the app is scanning for available thermometers
      • 0 - the app is not scanning for available thermometers

    Return Discovered Thermometers

    This function returns an associated array of thermometers within Bluetooth range that are above the Minimum Signal Strength (dBm) threshold set in Kiosk Pro settings. By default, the Minimum Signal Strength is set to -150, which should allow all thermometers in range to be returned. Setting a higher mimimum signal strength value may make it easier to distinguish multiple themometers in a single space.

    Format 
    kp_WBThermometerAPI_scanner_getDiscoveredThermometers(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(thermometers);
    Callback return values
    • thermometers - [associative array] containing an array of the discovered thermometers. Each thermometer object contains the following:
      • name - [string] the name of the device, always returned as 'TW_WANDBLUE'
      • initialDiscoveredRSSI - [string] the initial RSSI value for the device in dBm, representing the signal strength of the device
      • identifier - [string] the identifier generated by iOS/iPadOS for the CBPeripheral object - see Identifying a Specific Thermometer above for more detail
      • connectionState - [integer] representing the connection state of the device. Possible values are:
        • 0 - the device is not currently connected
        • 1 - the device is in the process of connecting
        • 2 - the device is connected
      • subscribingForGettingTemperatureState - [integer] representing whether the app is subscribed to temperature events. Possible values are:
        • 0 - the app is not currently subscribed to temperature events
        • 1 - the app is in the process of subscribing
        • 2 - the app is subscribed to temperature events

    Check Thermometers Rejected for Low Signal Strength

    This function returns an associated array of thermometers within Bluetooth range that have been rejected by the app for being below the Minimum Signal Strength (dBm) threshold set in Kiosk Pro settings. By default, the Minimum Signal Strength is set to -150, which should allow no thermometers in range to be returned through this call. Setting a higher mimimum signal strength value may make it easier to distinguish multiple themometers in a single space.

    Format 
    kp_WBThermometerAPI_scanner_getRejectedThermometers(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(thermometers);
    Callback return values
    • thermometers - [associative array] containing an array of the discovered thermometers. Each thermometer object contains the following:
      • name - [string] the name of the device, always returned as 'TW_WANDBLUE'
      • initialDiscoveredRSSI - [string] the initial RSSI value for the device in dBm, representing the signal strength of the device
      • identifier - [string] the identifier generated by iOS/iPadOS for the CBPeripheral object - see Identifying a Specific Thermometer above for more detail
      • connectionState - [integer] representing the connection state of the device. Possible values are:
        • 0 - the device is not currently connected
        • 1 - the device is in the process of connecting
        • 2 - the device is connected
      • subscribingForGettingTemperatureState - [integer] representing whether the app is subscribed to temperature events. Possible values are:
        • 0 - the app is not currently subscribed to temperature events
        • 1 - the app is in the process of subscribing
        • 2 - the app is subscribed to temperature events

    Select the Thermometer

    This function allows you to select the thermometer Kiosk Pro should use with the current phone or tablet. Selecting a specific thermometer allows you to return information about its current state and is required prior to connecting to a thermometer.

    Format 
    kp_WBThermometerAPI_device_attachWithId(thermometerIdentifier, callback);
    Parameters
  • thermometerIdentifier - [string] the identifier for a specific thermometer. Note that this identifier is generated and may change - more information on this here
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(thermometer);
    Callback return values
    • thermometer - [array] representing the attached thermometer. Formatted as an associative array of key-value pairs with the following keys:
      • name - [string] the name of the device, always returned as 'TW_WANDBLUE'
      • initialDiscoveredRSSI - [string] the initial RSSI value for the device in dBm, representing the signal strength of the device
      • identifier - [string] the identifier generated by iOS/iPadOS for the CBPeripheral object - see Identifying a Specific Thermometer above for more detail
      • connectionState - [integer] representing the connection state of the device. Possible values are:
        • 0 - the device is not currently connected
        • 1 - the device is in the process of connecting
        • 2 - the device is connected
      • subscribingForGettingTemperatureState - [integer] representing whether the app is subscribed to temperature events. Possible values are:
        • 0 - the app is not currently subscribed to temperature events
        • 1 - the app is in the process of subscribing
        • 2 - the app is subscribed to temperature events

    This function clears the currently selected thermometer if one exists.

    Format 
    kp_WBThermometerAPI_device_detach();

    Check Status of Selected Thermometer

    This function triggers a callback with information about the selected thermometer.

    Format 
    kp_WBThermometerAPI_device_getAttached(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(thermometer);
    Callback return values
    • thermometer - [associative array] containing the following values:
      • name - [string] the name of the device, always returned as 'TW_WANDBLUE'
      • initialDiscoveredRSSI - [string] the initial RSSI value for the device in dBm, representing the signal strength of the device
      • identifier - [string] the identifier generated by iOS/iPadOS for the CBPeripheral object - see Identifying a Specific Thermometer above for more detail
      • connectionState - [integer] representing the connection state of the device. Possible values are:
        • 0 - the device is not currently connected
        • 1 - the device is in the process of connecting
        • 2 - the device is connected
      • subscribingForGettingTemperatureState - [integer] representing whether the app is subscribed to temperature events. Possible values are:
        • 0 - the app is not currently subscribed to temperature events
        • 1 - the app is in the process of subscribing
        • 2 - the app is subscribed to temperature events

    Connect to Selected Thermometer

    This function triggers a Bluetooth connection with the selected thermometer. The connected thermometer can provide signal strength, but your code will also need to subscribe to temperature events successfully to return temperature data.

    Format 
    kp_WBThermometerAPI_device_connect(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(connectionProcessStarted);
    Callback return values
    • connectionProcessStarted - [integer] indicating whether Kiosk Pro was able to start the connection process
      • 1 - the connection process has started. Connecting via Bluetooth is a multi-step network process and this callback does not indicate that the connection process is complete.
      • 0 - the connection process was not started. This value will returned if no thermometer has been selected prior to triggering this function.
    Triggers

    Kiosk Pro will trigger kp_WBThermometerAPI_device_didConnect when the connection process is complete.

    Disconnect from Thermometer

    This function disconnects the app from a currently connected thermometer.

    Format 
    kp_WBThermometerAPI_device_disconnect(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(processStarted);
    Callback return values
    • processStarted - [integer] indicating whether Kiosk Pro was able to start the disconnection process
      • 1 - the disconnection process has started. Disconnecting via Bluetooth is a multi-step network process and this callback does not indicate that the disconnection process is complete.
      • 0 - the disconnection process was not started. This value will returned if no thermometer has been connected prior to triggering this function.
    Triggers

    Kiosk Pro will trigger kp_WBThermometerAPI_device_didDisconnect when the disconnection process is complete.

    Check Signal Strength

    This function triggers the app to return an RSSI value representing the signal strength of the thermometer.

    Format 
    kp_WBThermometerAPI_device_readRSSI(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(processStarted);
    Callback return values
    • processStarted - [integer] indicating whether Kiosk Pro was able to start requesting the signal strength value
      • 1 - the request process has started. Requests via Bluetooth are multi-step network processes and this callback does not indicate that the request process is complete.
      • 0 - the request process was not started. This value will returned if no thermometer has been connected prior to triggering this function.
    Triggers

    Kiosk Pro will trigger kp_WBThermometerAPI_device_didReadRSSI when the process is complete.

    Subscribe to Temperature Events

    This function subscribes the app to temperature notifications from the thermometer. As the ThermoWorks thermometer does not include a way to trigger the thermometer in their SDK, temperature scans must be triggered through a physical button press, either manually or through an automated trigger like Fingerbot.

    Format 
    kp_WBThermometerAPI_device_subscribeForGettingTemperature(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(processStarted);
    Callback return values
    • processStarted - [integer] indicating whether Kiosk Pro was able to start the process of subscribing to temperature events
      • 1 - the subscription process has started. Requests via Bluetooth are multi-step network processes and this callback does not indicate that the subscription process is complete.
      • 0 - the subscription process was not started. This value will returned if no thermometer has been connected prior to triggering this function.
    Triggers

    Kiosk Pro will trigger kp_WBThermometerAPI_device_didSubscribeForGettingTemperature when the process is complete.

    Notifications via API Callbacks

    After Request to Scan for Available Thermometers

    This callback is triggered after a request to begin scanning through kp_WBThermometerAPI_scanner_startDiscoveringThermometers with the result of that request.

    Format 
    kp_WBThermometerAPI_scanner_didStartDiscovering(error);
    Return values
    • error - [array] if undefined, scanning was started. If defined, the app was unable to successfully start scanning. Formatted as an associative array of key-value pairs with the following possible keys:
      • code
      • description
      • domain
      • debugDescription

    When a Thermometer Above Minimum Signal Strength Threshold is Discovered

    This callback is triggered when a new thermometer above the minimum signal strength (dBm) value configured in the app's settings is discovered while scanning is active. It will not trigger for thermometers currently attached through the API.

    Format 
    kp_WBThermometerAPI_scanner_didDiscoverThermometer(thermometer);
    Return values
    • thermometer - [array] representing the thermometer discovered. Formatted as an associative array of key-value pairs with the following keys:
      • name - [string] the name of the device, always returned as 'TW_WANDBLUE'
      • initialDiscoveredRSSI - [string] the initial RSSI value for the device in dBm, representing the signal strength of the device
      • identifier - [string] the identifier generated by iOS/iPadOS for the CBPeripheral object - see Identifying a Specific Thermometer above for more detail
      • connectionState - [integer] representing the connection state of the device. Possible values are:
        • 0 - the device is not currently connected
        • 1 - the device is in the process of connecting
        • 2 - the device is connected
      • subscribingForGettingTemperatureState - [integer] representing whether the app is subscribed to temperature events. Possible values are:
        • 0 - the app is not currently subscribed to temperature events
        • 1 - the app is in the process of subscribing
        • 2 - the app is subscribed to temperature events

    When a Thermometer Below Minimum Signal Strength Threshold is Rejected

    This callback is triggered when a new thermometer below the minimum signal strength (dBm) value configured in the app's settings is discovered and rejected while scanning is active.

    Format 
    kp_WBThermometerAPI_scanner_didRejectDiscoveredThermometer(thermometer);
    Return values
    • thermometer - [array] representing the thermometer discovered. Formatted as an associative array of key-value pairs with the following keys:
      • name - [string] the name of the device, always returned as 'TW_WANDBLUE'
      • initialDiscoveredRSSI - [string] the initial RSSI value for the device in dBm, representing the signal strength of the device
      • identifier - [string] the identifier generated by iOS/iPadOS for the CBPeripheral object - see Identifying a Specific Thermometer above for more detail
      • connectionState - [integer] representing the connection state of the device. Possible values are:
        • 0 - the device is not currently connected
        • 1 - the device is in the process of connecting
        • 2 - the device is connected
      • subscribingForGettingTemperatureState - [integer] representing whether the app is subscribed to temperature events. Possible values are:
        • 0 - the app is not currently subscribed to temperature events
        • 1 - the app is in the process of subscribing
        • 2 - the app is subscribed to temperature events

    After Request to Stop Scanning or When Scanning Ends by Timeout

    This callback is triggered after a request to stop scanning through kp_WBThermometerAPI_scanner_stopDiscoveringThermometers with the result of that request or through timing out.

    Format 
    kp_WBThermometerAPI_scanner_didStopDiscovering(error, isTimeout);
    Return values
    • error - [array] if undefined, scanning was stopped. If defined, the app was unable to end scanning (for example, because scanning was not currently happening at the time of the call). Formatted as an associative array of key-value pairs with the following keys:
      • code
      • description
      • domain
      • debugDescription
    • isTimeout - [integer] representing whether scanning stopped as result of a timeout. Possible values include:
      • 1 - scanning stopped as a result of a timeout
      • 0 - scanning did not stop as a result of a timeout

    After Request to Connect

    This callback is triggered after a request to connect to a thermometer through kp_WBThermometerAPI_device_connect with the result of that request.

    Format 
    kp_WBThermometerAPI_device_didConnect(error);
    Return values
    • error - [array] if defined, the app was unable to connect. Formatted as an associative array of key-value pairs with the following keys:
      • code
      • description
      • domain
      • debugDescription

    When Disconnected

    This callback is triggered when a thermometer is disconnected.

    Format 
    kp_WBThermometerAPI_device_didDisconnect(info);
    Return values
    • info - [array] if undefined, the thermomter was disconnected through an API call to kp_WBThermometerAPI_device_disconnect. If defined, the thermomter was disconnected for another reason (for example, the device turned off). Formatted as an associative array of key-value pairs with the following keys:
      • code
      • description
      • domain
      • debugDescription

    After Signal Strength Request

    This callback is triggered after a request to check the signal strength of the attached thermometer through kp_WBThermometerAPI_device_didReadRSSI, returning an updated value representing the current signal strength of the device.

    Format 
    kp_WBThermometerAPI_device_didReadRSSI(RSSI, error);
    Return values
    • RSSI - [string] the RSSI value of the thermometer in dBm, representing the signal strength of the device
    • error - [array] if defined, the app was unable to return an RSSI value. Formatted as an associative array of key-value pairs with the following keys:
      • code
      • description
      • domain
      • debugDescription

    After Request to Subscribe to Temperature Events

    This callback is triggered after a request to subscribe to any new temperature events returned by a connected thermometer through kp_WBThermometerAPI_device_subscribeForGettingTemperature.

    Format 
    kp_WBThermometerAPI_device_didSubscribeForGettingTemperature(error);
    Return values
    • error - [array] if defined, the app was unable to subscribe to temperature events. Formatted as an associative array of key-value pairs with the following keys:
      • code
      • description
      • domain
      • debugDescription

    When Temperature is Returned

    This callback is triggered by any new temperature events after subscribing to a connected thermometer.

    Format 
    kp_WBThermometerAPI_device_didUpdateTemperature(temperature, error);
    Return values
    • temperature - [array] if defined, represents the temperature returned by the device. Formatted as an associative array of key-value pairs with the following keys:
      • value - [integer] the temperature value returned in the temperature scale (Farenheit or Celsius) configured on the device. For example, '98.6'.
      • valueType - [integer] representing the temperature scale (Farenheit or Celsius) currently configured on the device. To switch between measurement modes, start with the thermometer turned off, then press 'Start' for 3 seconds, then the power button (while continuing to hold 'Start'). Possible values include:
        • 1 - Celsius
        • 2 - Farenheit
      • stringValue - [string] the complete temperature value and scale. For example, '98.6*F'.
    • error - [array] if defined, the app was unable to return a temperature value. Formatted as an associative array of key-value pairs with the following keys:
      • code
      • description
      • domain
      • debugDescription

    Sample Code

    • This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
    • To run sample code, set the app's homepage to kioskgroup.com/thermometers-wand-blue-api
    • To download a .zip of sample code, click here.

    Change Log

    • Added in version 10.0

    Related Articles

    Still stuck? How can we help? How can we help?