Setting Up Single-Purpose Devices

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.

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:

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.

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_password	The 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:

          Parameter	Description
          prov_package_name	The package name of the WSO2 Android agent. Make sure to use org.wso2.iot.agent as the default value.
          prov_package_locale	The language used. Android only recognizes specific languages. Therefore, make sure to add a language that is already specified. Example: en_US
          prov_package_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
          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_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. 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_password	The 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_encryption	If 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_location	The path of the APK file you hosted in step 1.7.
          prov_package_package_checksum	The 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

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. 

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

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.