||
Skip to end of metadata
Go to start of metadata

In this document, you will set up and use Corporate-Owned, Single-Use (COSU) devices also known as a kiosk devices with WSO2 IoT Server.

Before you begin

  • You will need a kiosk device. For testing purposes, you can use a factory reset device.  
  • Your device needs to support Near Filed Communication (NFC).
  • In WSO2 IoT Server this feature is only supported for devices that are Android 6.0 and above.
  • Download and install Android Studio. For more information, see installing Android Studio.

Use case

Alive & Healthy.Inc is a pharmaceutical company that distributes its products to many hospitals around the area. There had been many complaints about their delivery staff dropping off wrong products at the hospital. Therefore, the management decided to provide kiosk devices to the delivery staff to make it easy for them to track where the packages need to be delivered. Take a look at how this helped Alive & Healthy.Inc:

  • Let's say the delivery employee is Alex. Alex Near Field Communication (NFC) bumps the kiosk device using his device to get the details of the package he needs to deliver.
  • Once Alex's details are recognized by the system, the details of the package that needs to be delivered are sent to the device.  
  • Alex then goes to the collection point and request for the package by showing the package details.
  • Once the package is received, Alex scans the QR code on it to get the details and direction of the drop off point.
  • On reaching the delivery point, Alex hands off the package to the hospital and get the signature on the goods received note.
  • After completing the task and after the data is recorded, the kiosk device erases Alex's details and goes back to the default state.
    Once back at Alive & Healthy.Inc, Alex returns the device and waits for his call again. 

To make the above scenario work, you need to install the required applications on the device and make sure the devices are managed correctly. Let's take a look how you can use WSO2 IoT Server to configure and manage your single-purpose/kiosk devices.

Step 1: Customizing the Android Agent

The Android agent needs to be customized to enable the kiosk features. Follow the steps given below:

Before you begin, you need to have Android Studio installed. For more information, see installing Android Studio.

  1. Replace the android.jar file that is in the <ANDROID>/sdk/platforms/android-<CURRENT_API_LEVEL> directory with the android.jar file found here.

    Why is this needed?

    The WSO2 Android agent requires access to hidden APIs (APIs that are available at runtime). Therefore, you need to replace the anrdoid.jar file as mentioned in this step.

  2. Download or clone the Android agent source code. The folder will be referred to as <ANDROID_AGENT_SOURCE_CODE> throughout the documentation.
  3. Open the client folder that is in the <ANDROID_AGENT_SOURCE_CODE>/client directory via Android Studio.

  4. WSO2 IoT Server supports API levels 16 to 25. Therefore, install the Android API levels 16 to 25 on Android Studio.
    1. Open Android Studio.
    2. Click SDK Manager.
    3. Click the SDK Platform tab and select the 16 and 25 API levels.
      Example:
    4. Click Apply.
  5. Open the build.gradle file, and configure the parameters given below under the debug build variant.

    To make sure you are building the correct build variant via Android Studio, click Build > Select Build Variants and check what's been built.

    DEFAULT_OWNERSHIP

    Define COSU as the value.

    DEFAULT_HOST

    Define <NETWORK_IP>:8280 as the value for HTTP communication.

    All devices must be connected to the same network.

    Example: 

    // Set DEFAULT_OWNERSHIP to null if no overiding is needed. Other possible values are,
    // BYOD or COPE. If you are using the mutual SSL authentication
    // This value must be set to a value other than null.
    buildConfigField "String", "DEFAULT_OWNERSHIP", "\"COSU\""
    //DEFAULT_HOST - Hardcode the server host to avoid having the user type it during
    //enrollment. If the user must type the hostname/IP during enrollment, leave it as null.
    buildConfigField "String", "DEFAULT_HOST", "\"http://192.168.12.110:8280\""
  6. Build the project to create a new APK with the changes.  The new client-debug.apk file is created in the < ANDROID_AGENT_SOURCE_CODE>/client/client/build/outputs/apk directory.

  7. Upload the APK file to a public location, such as GitHub. You will need this step later on when customizing the NFC provisioning application.

    To get the downloadable APK file path from GitHub, click on the uploaded file, right click on view raw, and copy the link. Use this link when customizing the NFC provisioning application.

Let's take a look at other configurations you can do to improve the Android agent by configuring the build.gradle file as listed below:

  • By default, you can install many applications on your kiosk device. Configure the Android agent that is configured for COSU, to install only one application by defining false as the value for the ALLOW_MULTIPLE_APPS_IN_COSU_MODE property under the debug section.

    buildConfigField "boolean", "ALLOW_MULTIPLE_APPS_IN_COSU_MODE", "false"
  • Disable the DISPLAY_WIPE_DEVICE_BUTTON and COSU_SECRET_EXIT properties in a production environment. These are enabled by default so that you can use the kiosk device in a testing environment by factory resetting the device or by clicking the WSO2 logo six times to exit the COSU mode. Therefore, we strongly recommend disabling these settings in the production environment.

    buildConfigField "boolean", "DISPLAY_WIPE_DEVICE_BUTTON", "false"
    buildConfigField "boolean", "COSU_SECRET_EXIT", "false"
  • Optionally, enable the HIDE_LOGIN_UI property to hide the login page.

    public static final boolean HIDE_LOGIN_UI = true;

Step 2: Customizing the WSO2 NFC Provisioning application

You need to configure the NFC provisioning application to provision the WSO2 Android agent. Let's take a look at how it's done.

  1. Download or clone the devicemgt-nfc-provisioning-android from GitHub.
  2. Import the project into Android Studio.

    Before you begin

    Make sure to have the following:

    • Android SDK 25
    • Android Build Tools v25.0.2
    • Android Support Repository
  3. Run the following command to get the checkSum value of the agent, which was created in step 1.6.

    cat <THE FILE PATH OF THE APK FILE YOU CREATED IN STEP 1.6.> | openssl dgst -binary -sha1 | openssl base64 | tr '+/' '-_' | tr -d '='

    Example:

    cat <ANDROID_AGENT_SOURCE_CODE>/client/client/build/outputs/apk/client-debug.apk | openssl dgst -binary -sha1 | openssl base64 | tr '+/' '-_' | tr -d '='
  4. Open the build.gradle file, and configure the DEFAULT_HOST parameter that is under the  debug  build variant.

    • If you are using HTTP for testing purposes, configure the parameter as shown below.

      buildConfigField "String", "DEFAULT_HOST", "\"http://172.20.10.2:8280\""
    • If you are using HTTPS in a production environment, configure the parameter as shown below.

      buildConfigField "String", "DEFAULT_HOST", "\"https://172.20.10.2:8243\""

      To successfully configure the application for HTTPS, you need to follow the same steps given under Configuring Android for HTTPS Communication.

  5. Define the values that need to be entered in the NFC application by configuring the devicemgt-nfc-provisioning-android/resources/app/res/values/configurations.xml file. These values are used in step 3.3

    If you want to change the values once the application is installed, you need to update the settings in the applications as shown in step 3.3.

    <resources>
        <string name="package_name">org.wso2.iot.agent</string>
        <string name="package_download_location">http://192.168.8.151:8000/client-debug.apk</string>
        <string name="package_checksum">3ZqkN92u0I7jbQoDuIrOaOZ7IPE</string>
        <string name="wifi_ssid">Dialog 4G</string>
        <string name="wifi_security_type" >WPA</string>
        <string name="wifi_password">123456</string>
        <string name="time_zone">Asia/Colombo</string>
        <string name="locale">en_US</string>
        <string name="encryption">false</string>
        <string name="kiosk_app_download_location">http://192.168.8.151:8000/Calculator.apk</string>
    </resources>

    Let's get to know the properties that are used.

    package_name

    The package name of the WSO2 Android agent. Don't change the default value defined here.

    package_download_location

    The path of the APK file you hosted in step 1.7.

    package_checksum

    The checksum value of the agent you got in step 2.3.

    wifi_ssid

    The SSID of the Wi-Fi network that should be used during NFC device owner provisioning for downloading the mobile device management application. 

    wifi_security_type

    The Wi-Fi security type of your network. The most common types of wireless security are Wired Equivalent Privacy (WEP), Wi-Fi Protected Access (WPA) and NONE if there is no password.
    wifi_passwordThe password of the Wi-Fi network.

    time_zone

    The time zone that your network belongs to. Android only recognizes specific time zones. Therefore, make sure to add a time zone that is already specified.
    Example: Asia/Colombo

    locale

    The language used. Android only recognizes specific languages. Therefore, make sure to add a language that is already specified.
    Example: en_US

    encryption

    If the default value is set to false the kiosk device will not be encrypted when NFC bumped. Therefore, define the default value as false.

    kiosk_app_download_location

    This property is not required for the standalone pack and is only required for a cloud deployment. Define the APK location of the app you want to download after provisioning your KIOSK device.
    If you want to enable this setting, open the app build.gradle file and configure the PUSH_KIOSK_APP property that is under the debug variant as follows:

    buildConfigField "boolean", "PUSH_KIOSK_APP", "true"
  6. Optionally, configure the settings to access the NFC application via Firebase Remote Configurations. Generally, it is the device management administrator who defines the default values for the above step. If you want an individual other than the device management administrator to NFC bump the devices, you need to follow the steps given here.

     Click here to find out the steps you need follow.
    1. To enable the firebase remote configuration for the NFC application, configure the USE_REMOTE_CONFIG prop app in the build.gradle file.

       buildConfigField "boolean", "USE_REMOTE_CONFIG", "true"
    2. Go to the Firebase API Console.
    3. Click CREATE NEW PROJECT.
    4. Provide a preferred name for the project (example: NFC-Application), select the country/region, and click CREATE PROJECT.

      The new project will be created in few seconds, and you will be navigated to the overview page of the project.

    5. Click Add Firebase to your Android App on the overview page of the project.

    6. Provide the package name of the WSO2 Android agent, which is org.wso2.iot.nfcprovisoning and click ADD APP.

      The generated  google-services.json file downloads. If the file didn't download check step g.

    7. Click CONTINUE > FINISH to finish the process and create the application. 
      You will then be navigated to the overview of the created application.
    8. Optionally, if the google-services.json file did not download, follow the steps given below to download it.
      1. Click on your application and click settings.
      2. Click the download google-services.json button.
    9. Replace the devicemgt-nfc-provisioning-android/app/google-services.json file with the google-services.json  file you downloaded.
    10. Add the fields that need to be shown in the NFC application as shown in step 3.4.

      1. Click on your firebase application and click Remote Config on the left navigation.
      2. Add the following parameters and their default values:

        ParameterDescription
        prov_package_nameThe package name of the WSO2 Android agent. Make sure to use org.wso2.iot.agent as the default value.
        prov_package_localeThe language used. Android only recognizes specific languages. Therefore, make sure to add a language that is already specified.
        Example: en_US
        prov_package_time_zoneThe time zone that your network belongs to. Android only recognizes specific time zones. Therefore, make sure to add a time zone that is already specified.
        Example: Asia/Colombo
        prov_package_wifi_ssid

        The SSID of the Wi-Fi network that should be used during NFC device owner provisioning for downloading the mobile device management application. 

        If you are unsure of the Wi-Fi network that is being used, do not define a default value. You can enter the Wi-Fi SSID from the application configuration screen.

        prov_package_wifi_typeThe Wi-Fi security type of your network. The most common types of wireless security are  Wired Equivalent Privacy  ( WEP ), Wi-Fi Protected Access (WPA) and NONE if there is no password.

        If you are unsure of the Wi-Fi network that is being used, do not define a default value. You can enter the Wi-Fi type from the application configuration screen.
        prov_package_wifi_passwordThe password of your Wi-Fi network.

        If you are unsure of the Wi-Fi network's password, do not define a default value. You can enter the WiFi SSID from the application configuration screen.
        prov_package_skip_encryptionIf the default value is set to true the kiosk device will not be encrypted when NFC bumped. Therefore, define the default value as true.
        prov_package_package_locationThe path of the APK file you hosted in step 1.7.
        prov_package_package_checksumThe checksum value of the agent you got in step 2.3.

        Example:

  7. Build the APK file.
    Once the build completes, the .apk file is created in the <android-NfcProvisioning>/Application/build/outputs/apk directory.

Step 3: Installing the NFC application on your device

  1. Install the NFC application on your device.

    You need to make the NFC Provisioning APK file publicly accessible, so users can download it onto their device.

    Don't have a place to host the NFC application? You can use WSO2 IoT Server for this. Enroll your device with WSO2 IoT Server, publish the NFC provisioning application to the app publisher, and install them on your device via the app store.

  2. Tap Install on your device to finish installing the application.
  3. Sign in to the NFC application using your username, password, and organization. If you are using the application locally, enter carbon.super for the organization.
    Example:

  4. The default values you defined in Step 2 are pushed to the installed NFC application. If you want to change the values, click configurations and update the values.

    Example: 

Now you can start using the application to NFC bump the kiosk device and register it with WSO2 IoT Server under your user account.

Step 4: Installing the Android agent on the kiosk device

Before you begin

  • Start the WSO2 IoT Server core and analytics scripts respectively.

    cd <IOTS_HOME>/bin  
    ------Linux/Mac OS/Solaris ----------
    ./iot-server.sh
    ./analytics.sh
      
    -----Windows-----------
    iot-server.bat
    analytics.bat
  • Make sure to enable the Android Beam setting on your device.
    To enable the Android Beam, tap on Settings > NFC and Payment and enable it.
  • Factory reset your kiosk device or use a kiosk device.

    Once the device is reset do not tap anything, only follow the steps given below.

  1. NFC bump your device and the kiosk device.

    Not sure what to do?

    Bring the devices close to each other and tap them. 

  2. Your kiosk device will connect to the Wi-Fi connection based on the settings you have defined in the NFC provisioning application.

    If the Wi-Fi SSID and password are not defined properly, the device will fail to connect to the network and you will not be able to proceed.

  3. The WSO2 Device Management agent downloads and installs on the kiosk device.

    How does this happen automatically?

    In step 2.4 you configured the NFC application to download the customized Device Management agent. When you NFC bump the devices, the kiosk device will start downloading the agent application.

Now you won't be able to use the default apps on the kiosk device. You can only use the applications installed via the WSO2 Android agent. Now let's install applications on the kiosk device.

Step 5: Installing the required applications on the kiosk device

Once the Android agent is installed on the kiosk device, the mobile device management administrators can install the required applications on the device and manage the device via the WSO2 IoT Server. 

You are not able to install web clips on the kiosk device as it would require the user to access the web browser, which restricted on a kiosk device.

Let's take a look at how you can install an application on the kiosk device. 

Before you begin

For this use case, you need to create another application and publish it from the app publisher to the store.

To make it easy for you to understand, let's create the Android app catalog application that we used in our quick start guide and install it on the kiosk device.

 Click here for more information.
  1. Sign in to the App Publisher using the following URL: https://<IoT_HOST>:9443/publisher
  2. Click Add New Mobile Application that is under the Mobile Application drop down.
  3. Select Android for Platform on which the application (app) will be based on.
  4. Select the Enterprise Store Type.
  5. Upload the nfc-app.apk file that is in the <IoT_HOME>/samples/mobile-qsg/apps/android directory.
  6. Click Next, and you will get the following screen:
  7. Enter the following details of the app.

    • Name - The full name of the app.
    • Display Name - The name of the app that is displayed to the user.
    • Description -  A summarized description of the app.
    • Recent Changes - Optional. A summarized description of what is new in this app when compared to its previous version.
    • Version - Version of the public application. If you have previously entered a different version of this app, make sure to enter a unique version number.
    • Category - Select the category that this app needs to be listed under.
    • Visibility - Enter the user roles that this app will be visible to.
    • Tags - You can group mobile applications under a specific category using tags.  Define the category and press enter.Click on the respective + buttons to upload the required images.
      • Banner - Image that will appear as the app banner.
      • Screenshots - Screenshots of the app so that the user can get an understanding of what the app offers. A maximum of four screenshots are allowed.
      • Icon file - The image that will be used as the application icon in the Store and when the application is installed on a device.

      The recommended image extension is .png while the recommended dimensions are as follows:

      • Icons: 124px x 124px
      • Screenshots: 288px x 512px (landscape) and 512px x 288px (portrait)
      • Banners: 705px x 344px
  8. Click Create. The created app is shown in the created list of apps.
  9. Click on the application you created in the https://<IoT_HOST>:9443/publisher.
  10. Click Submit for Review > Approve > Publish.

  11.  The application is now published and is available in your App Store.

  1. Navigate to the App Store using the following URL:  https://<IoT_HOST>:9443/store 

  2. Sign in using your username and password.

  3. Click on the mobile application you want to install, and click Install.

    Want to install the application on many COSU devices?

    In this step, you click Install, because you are only installing the application on one device.
    Let's say you have many devices and want to install the application in one go on all of those devices. Click Ent. Install and select the users or user roles of the device owner for that the application needs to be installed on the respective devices.

    Example:

  4. Select Instant install, and click Yes.
  5. Click on your kiosk device in the pop-up menu to install and subscribe to the application.
    A success message will be shown when you have successfully subscribed to the application.
  6. On your kiosk device, tap Install to finish installing the application.
    You can install many applications on your kiosk device by default. If you configured the settings to only install one application as described here, you will only be able to install one application on the kiosk device.The users will only be able to use the applications you install.
    Example:

What's next?

  • Once you are done using the device, device administrators can factory reset the device. 

     Click here to expand...
    1. On the device management console home page, click View under Devices.
    2. Click on the kiosk device, and click on the Wipe Data operation that is under device operations.
      If you don't have a PIN on your kiosk device, you can leave the field empty and carry out the operation.
  • Manage the system updates COSU devices by publishing a policy on them. For more information, see Adding a System Update Policy for COSU Devices.
  • No labels