--- title: "Bluetooth Scanner Implementation Guide" slug: "bluetooth-scanner-implementation-guide" updated: 2024-03-26T09:22:05Z published: 2024-03-26T09:22:05Z canonical: "help.pillir.io/bluetooth-scanner-implementation-guide" --- > ## Documentation Index > Fetch the complete documentation index at: https://help.pillir.io/llms.txt > Use this file to discover all available pages before exploring further. # Integration of Bluetooth Scanner Device with EdgeReady Apps ## Overview The EdgeReady platform includes support for Bluetooth devices, which allows Apps built on the platform to wirelessly exchange data with connected Bluetooth devices. This guide outlines the steps to seamlessly integrate a Bluetooth scanner device with your EdgeReady App. By following these instructions, you'll enhance your app's functionality, allowing users to interact with external Bluetooth-enabled scanners. ## Integration Summary - The Bluetooth scanner configurations are executed within the Login Microapp in the following screens: - Settings Screen - Home Screen - EdgeReady App Main Screen Configuration - Publishing and Deploying the Container App - Testing the Connection ## Pre-requisites - Build the EdgeReady App in the App Process Modeler based on the business requirement - Publish and Preview the App - Download the Login MicroApp template from Library > New login - Access to a Bluetooth scanner device compatible with the EdgeReady platform. ## Use Case: Barcode Scanning to Read Item Details **Scenario**: In this use-case, end-users use a Bluetooth scanner connected to their iPad or mobile devices. The primary task involves scanning barcodes that is received by the Apps. Subsequently, the App displays the details related to the scanned barcode item. NoteThe following configurations are explained to meet the above use-case requirement. While specific Bluetooth configurations can differ across various business use-cases, the fundamental setup involves the steps detailed below. You may add additional customizations based on your specific business requirements. ## Scanner Configurations in the Login Microapp ## Settings Screen 1. After creating a new Login microapp, click the **Settings** screen page.![a-settingscreen-page](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/a-settingscreen-page.png) 2. Click the **Behavior tab**, add the following logic blocks for the Settings > **onPageShow** event.![1-Settingsscreen-behav-](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/1-Settingsscreen-behav-.png) ### onPageShow Logic This logic will retrieve the list of scanner devices in the vicinity and store in the **bluetooth_device** BF variable. This variable is mapped to a datagrid component in the **Settings** screen.![b-datagridcomp-settingscreen](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/b-datagridcomp-settingscreen.png) **Conditional Display for Non-Mobile Devices:** ![c-onPageShowlogic-firstpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/c-onPageShowlogic-firstpart.png) - Checks if the "**IsMobile**" state is set to "**false"** (indicating a non-mobile device). - If true, set the display style of two elements with IDs 'grid2_row_2' and 'grid2_row_3' to "**none**" - effectively hiding them. NoteThe above step is optional and can be included based on the business requiremen **Display for Mobile Device:![c-onPageShowlogic-secondpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/c-onPageShowlogic-secondpart.png)** - If the device is identified as a mobile device, it sets the "**connection_status**" state to '**Getting Device List**'. *(This is an optional step (Optional step intended for debugging: Include if necessary.)* - Invokes an asynchronous function to retrieve the list of available devices using the **BTDeviceGetList** block. - After successful retrieval, it updates the "**bluetooth_device**" BF variable with the obtained list. In case of an error during device list retrieval, the error is handled in the second callback function, but the specific actions within this callback are not provided. ### Connect Button Logic In the Settings screen, the user can view the list of available bluetooth devices and clicks the **Connect** button of the selected device. The following behavior is executed:![d-settingscreen-connectbtn-behav](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/d-settingscreen-connectbtn-behav.png) **Setting Bluetooth Device ID:![d-settingscreen-connectbtn-behav-firstpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/d-settingscreen-connectbtn-behav-firstpart.png)** - The Set block retrieves the "**name**" property from the clicked object and sets it as the "**bluetooth_device_id**". - The Set Local Key block stores the "bluetooth_device_id" in a local storage variable. - This step aims to automatically connect bluetooth devices when the user utilizes the bluetooth scanner for subsequent logins. **Updating the Connection Status:![d-settingscreen-connectbtn-behav-secondpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/d-settingscreen-connectbtn-behav-secondpart.png)** - Sets the "**connection_status**" state to indicate the ongoing process of connecting to the Bluetooth device. - The status includes the name(bluetooth_device_id) of the Bluetooth device. **Pairing and Connecting to the Device:![d-settingscreen-connectbtn-behav-thirdpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/d-settingscreen-connectbtn-behav-thirdpart.png)** - Using the BTPairDevice block, calls the pair device function by passing the "**bluetooth_device_id**". - On successful pairing, it proceeds to connect to the device using BTConnectDevice block. - On successful connection, it updates the "**connection_status**" to indicate that the device is connected. **Listening for Events:![d-settingscreen-connectbtn-behav-fourthpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/d-settingscreen-connectbtn-behav-fourthpart.png)** - Using the BTListenDevice block, calls the listen function, and passes the "**bluetooth_device_id**". - On receiving data from the connected device, it publishes the data using **window.pubsub.publish**. window.pubsub.publishIt is a customized function designed to optimize the scanner logic. This function is triggered once the listening process is initiated. This function call is invoked after the listening is initiated.  The call invokes the [**pubsub.js**](/v1/docs/bluetooth-scanner-implementation-guide#appendix-a) file(Library > Assets).  ## Home Screen When the user clicks the home screen in the Login MicroApp, the following logic is executed automatically as an onPageShow event. | ![e-homescreenlogic-1](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-1.png) | ![e-homescreenlogic-2](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-2.png) | ![e-homescreenlogic-3](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-3.png) | ![e-homescreenlogic-4](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-4.png) | | --- | --- | --- | --- | **Checking Bluetooth Device and Session Status:![e-homescreenlogic-1stpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-1stpart.png)** - Checks if a Bluetooth device ID is stored in local storage and if the session status for the scanner is not set to 'True.' **Connecting to the Bluetooth Device:![e-homescreenlogic-2ndpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-2ndpart.png)** - If the conditions are met, retrieve the Bluetooth device ID from local storage. - Using the BTGetDevice List block it gets the list of available Bluetooth devices. - Iterates through the list and checks if the stored device ID matches any available device. - If the device is not connected, it attempts to connect, updates the connection status, and starts listening for events. - If the device is already connected, it updates the status and starts listening for events. **Listening for Events and Publishing:![e-homescreenlogic-3rdpart](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-3rdpart.png)** - When successfully connected, it listens for events from the Bluetooth device. - If events are received, it updates the connection status and publishes the events to the required Apps using window.pubsub.publish in assert. *(here **Cycle_Counting** is the name of the business function that is passed as an object to the Function call)* - A session key is set up in the listen block - if the user closes the App and then returns to the home screen, the listening event should not be initiated again. For this purpose the session variable is used. It will check if the listening is initiated and continues with the data communication, if not the logic is executed from the beginning.![e-homescreenlogic-3rdpart-sessionkey](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/e-homescreenlogic-3rdpart-sessionkey.png) - In case of connection errors, it updates the connection status accordingly. **Handling Non-Mobile Devices or Inactive Scanner:** - If the Bluetooth device ID is not found in local storage or the session status is '**True**,' it checks if the device is a mobile device. - If it is a mobile device and the session status indicates an active scanner session, it sets the connection status to '**Already Listening**'. - If it is a mobile device but the session status is not '**True**,' it prompts the user to go to the **Settings** screen to pair and connect with the Bluetooth scanner, triggering an '**onclick**' event of the Settings button in the home screen. ## Scanner Configuration in the Main Page of the Business Function The following logic is executed in the main screen of the business function as an **onPageShow** event.![f-homescreen-appmainscreen](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/f-homescreen-appmainscreen.png) - On checking if the device is paired, invoke the function call **publish.subscribe**. *(Here **i****nventory_lookup** is the name of the business function that is passed as an object to the Function call)* - In success callback, get the scanned value(x1). The value is fetched as eventname:value in json format. - The Function Call **validateinpBatch** converts the scanned value to the required format. This function references the [**scanner.js**](/v1/docs/bluetooth-scanner-implementation-guide#appendix-a) file in the Library > Assets. *(This is an optional step specific to the business requirement.)* - Now the **get details** event is triggered to display the details of the scanned value in the App screen. **Calling the Unsubscribe Function** - From the main screen of app, if the user clicks the home button- the unsubscribe event is called to disconnect the listening event. | ![g-unsubscribe-1](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/g-unsubscribe-1.png) | ![g-unsubscribe-2](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/g-unsubscribe-2.png) | | --- | --- | ## Final Steps - Once the Login Microapp is created and customized, it must be published. The steps to publish the login app are similar to EdgeReady apps and can be referred in [Preview-Publish-Transport](https://help.pillir.io/docs/preview-publish-transport-section) Apps section. - After the login app is published, it is available for deployment for any project under the current tenant. Refer [Deploying the Login](https://help.pillir.io/docs/logins-1#deploying-the-login-app) App section for deployment steps. ## Testing the Connection To connect to the bluetooth scanner device, do the following: 1. Install the App on your device. 2. Open the App and go to the **Settings** screen from the main menu. 3. Select the bluetooth scanner device and click **Connect**.![Image_20240130_122706](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/Image_20240130_122706.png) Once the connection is established, the device is now ready for scanning operations. After this initial setup, subsequent logins to the App will automatically connect the scanner device. ## Appendix A - .js files The following scripts are the list of .js files added to the **Library > Assets** section. These scripts are invoked in the different behaviors of the bluetooth device configurations. [pubsub.js](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/pubsub.js)[scanner.js](https://cdn.document360.io/718af901-247b-46be-8ace-83da21839237/Images/Documentation/scanner.js) ## Appendix B - Variables The following list of variables are created in the Login Microapp APM screen, for the Bluetooth scanner device integration. | Variable Name | Datatype | Scope | | --- | --- | --- | | bluetoooth_device | Table | Used to store the device name, model ,identifer and state | | bluetooth_device_id | String | Used to store the device name. | | Connection_status | String | Used to Store the connection status of the device. | NoteThe variables declared within a Login Microapp are not available outside of it.