API: Control & Trigger Fingerbot Button Press

Remotely trigger buttons and switches by connecting to a Fingerbot Bluetooth actuator. This functionality is great for kiosk deployments that need to physically trigger something using the iPad, or for home automation.

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
    • JavaScript > Access JavaScript API > By Import
  • iOS/iPadOS Permissions
    • Bluetooth - more on enabling specific iOS/iPadOS permissions here
  • Physical Hardware
    • unencrypted Fingerbot device. More information about Fingerbot is available here, but the Fingerbots available for sale on the Adaprox site are encrypted and can not be used with Kiosk Pro.  For information on ordering compatible Fingerbot devices directly from Kiosk Group, contact us directly. 

Triggers via API Functions

Scan for Fingerbot

This function scans for Fingerbots.

Format 
kp_FingerbotAPI_startScan();
Triggers This call immediately triggers kp_FingerbotAPI_didUpdateScanningState. If the scan fails to find a new Fingerbot it will trigger kp_FingerbotAPI_didFailToDiscoverNewDevices. If the scan fails due to a Bluetooth connection problem it will trigger kp_FingerbotAPI_didFailToDiscoverDevicesDueToBluetoothProblems.

Stop Scanning for Fingerbot

This function stops scanning for Fingerbots.

Format 
kp_FingerbotAPI_stopScan();
Triggers This call immediately triggers kp_FingerbotAPI_didUpdateScanningState.

Get List of Connected Fingerbots

This function gets a list of Fingerbots that are currently connected.

Format 
kp_FingerbotAPI_getAllConnectedDevices();
Triggers This call immediately triggers kp_FingerbotAPI_didUpdateDeviceList.

Check if Fingerbot is Connected

This function checks if a specific Fingerbot is connected.

Format 
kp_FingerbotAPI_isDeviceConnected(deviceId);
Parameters
  • deviceId - [string] the Fingerbot identifier
    		•
    Triggers If the Fingerbot is connected, this call triggers kp_FingerbotAPI_didConnectToDevice. Otherwise, this call triggers kp_FingerbotAPI_didDisconnectFromDevice. If the device cannot be found then kp_FingerbotAPI_didFailFindDeviceWithId will be triggered.

    Update Fingerbot Firmware

    This function updates the firmware on a specific Fingerbot. Note: calling this function disconnects the device, so you'll need to re-connect using kp_FingerbotAPI_connectToDevice after the update is finished.

    Format 
    kp_FingerbotAPI_updateFirmwareVersionOnDevice(deviceId);
    Parameters
  • deviceId - [string] the Fingerbot identifier
    		•
    Triggers This call immediately triggers kp_FingerbotAPI_disconnectFromDevice, unless Kiosk Pro fails to find the device, in which case kp_FingerbotAPI_didFailFindDeviceWithId will be triggered. After you re-connect the Fingerbot, the kp_FingerbotAPI_didUpdateFirmwareVersionOnDevice callback will trigger.

    Connect to Fingerbot

    This function connects to a specific Fingerbot.

    Format 
    kp_FingerbotAPI_connectToDevice(deviceId);
    Parameters
  • deviceId - [string] the Fingerbot identifier
    		•
    Triggers When connected, this call triggers kp_FingerbotAPI_didConnectToDevice. If the Fingerbot could not be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered. If the firmware was updated, this call will trigger When Firmware is Updated.

    Disconnect from Fingerbot

    This function disconnects from a specific Fingerbot.

    Format 
    kp_FingerbotAPI_disconnectFromDevice(deviceId);
    Parameters
  • deviceId - [string] the Fingerbot identifier
    		•
    Triggers When disconnected, this call triggers kp_FingerbotAPI_didDisconnectFromDevice. Otherwise, this call triggers kp_FingerbotAPI_didFailFindDeviceWithId.

    Send Click Request to Fingerbot

    This function sends a click request to a specific Fingerbot.

    Format 
    kp_FingerbotAPI_clickOnDevice(deviceId);
    Parameters
  • deviceId - [string] the Fingerbot identifier
    		•
    Triggers This call trigger when the click request is successful. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.

    Get Battery Level from Fingerbot

    This function gets the battery percentage of a specific Fingerbot.

    Format 
    kp_FingerbotAPI_refreshBatteryOnDevice(deviceId);
    Parameters
  • deviceId - [string] the Fingerbot identifier
    		•
    Triggers This call triggers kp_FingerbotAPI_didRefreshBatteryOnDevice. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.

    Set Sustain Time on Fingerbot

    This function

    Format 
    kp_FingerbotAPI_setSustainTimeOnDevice(deviceId, time);
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • time - [integer] the amount of time for the click to hold. Allowed values range from 0.2 to 10 seconds.
    		•
    Triggers This call triggers kp_FingerbotAPI_didUpdateSustainTimeOnDevice. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.

    Set Down Movement on Fingerbot

    This function

    Format 
    kp_FingerbotAPI_setDownMovementOnDevice(deviceId, percent);
    Parameters
  • deviceId - [string] the Fingerbot identifier
  • percent - [integer] how deep the Fingerbot should click. Allowed values range from 51 to 100 percent.
    		•
    Triggers This call triggers kp_FingerbotAPI_didUpdateSustainTimeOnDevice. If the Fingerbot cannot be found, kp_FingerbotAPI_didFailFindDeviceWithId is triggered.

    Notifications via API Callbacks

    When Scanning Status Changes

    This callback is triggered when the scan for Fingerbots starts or ends.

    Format 
    kp_FingerbotAPI_didUpdateScanningState(isScanning);
    Return values isScanning - [integer] the status of the scan. Possible values include:
    • 0 - scanning ended
    • 1 - scanning started

    When Scanning Fails Due to Bluetooth

    This callback triggers if scanning fails because Bluetooth is turned off.

    Format 
    kp_FingerbotAPI_didFailToDiscoverDevicesDueToBluetoothProblems();

    When a Fingerbot Cannot be Found

    This callback triggers when a scan fails to find new devices.

    Format 
    kp_FingerbotAPI_didFailToDiscoverNewDevices(callback);

    When the Fingerbot List is Updated

    This callback triggers when a Fingerbot is found after scanning.

    Format 
    kp_FingerbotAPI_didUpdateDeviceList(deviceList);
    Return values
    • deviceList - [array] contains information about the device(s), including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier

    When a Fingerbot with the Specified ID Cannot be Found

    This callback triggers when trying to communicate with a specific Fingerbot fails.

    Format 
    kp_FingerbotAPI_didFailFindDeviceWithId(callback);
    Return values deviceId - [string] the Fingerbot identifier

    When Firmware is Updated

    This callback triggers after connecting to a Fingerbot that had its firmware updated.

    Format 
    kp_FingerbotAPI_didUpdateFirmwareVersionOnDevice(device, version);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • version - [string] the firmware version number

    When Getting Battery Status is Successful

    This callback triggers when getting the battery status of a Fingerbot is successful.

    Format 
    kp_FingerbotAPI_didRefreshBatteryOnDevice(device, level);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • level - [integer] the percentage of the Fingerbot's battery level

    When Fingerbot Charging Status Changes

    This callback triggers when the charging status of a connected Fingerbot changes.

    Format 
    kp_FingerbotAPI_didUpdateChargingOnDevice(device, chargingStatus);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • chargingStatus - [string] whether the Fingerbot is charging. Possible values:
      • None - not charging
      • Charging - charging

    When Fingerbot is Connected

    This callback triggers when a Fingerbot is connected.

    Format 
    kp_FingerbotAPI_didConnectToDevice(device);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier

    When Fingerbot is Disconnected

    This callback is triggered when a Fingerbot is disconnected.

    Format 
    kp_FingerbotAPI_didDisconnectFromDevice(device);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier

    When Fingerbot is Clicked

    This callback is triggered when a Fingerbot successfully receives a click request.

    Format 
    kp_FingerbotAPI_didClickOnDevice(device);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier

    When Down Movement is Updated

    This callback triggers after the down movement of the Fingerbot is updated.

    Format 
    kp_FingerbotAPI_didUpdateDownMovementOnDevice(device, percent);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • percent - [integer] the percentage of depth the Fingerbot should move when clicking

    When Sustain Time is Updated

    This callback triggers after a Fingerbot's sustain time is updated.

    Format 
    kp_FingerbotAPI_didUpdateSustainTimeOnDevice(device, time);
    Return values
    • device - [array] information about the Fingerbot including:
      • isConnected - [integer] whether the device is connected. Possible values:
        • 0 - disconnected
        • 1 - connected
      • deviceId - [string] the Fingerbot identifier
    • time - [integer] the number of seconds that the Fingerbot should stay down when clicking

    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/fingerbot-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?