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.
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.
Replace the
android.jar
file that is in the<ANDROID>/sdk/platforms/android-<CURRENT_API_LEVEL>
directory with theandroid.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.- Download or clone the Android agent source code. The folder will be referred to as
<ANDROID_AGENT_SOURCE_CODE>
throughout the documentation. Open the client folder that is in the
<ANDROID_AGENT_SOURCE_CODE>/client
directory via Android Studio.- WSO2 IoT Server supports API levels 16 to 25. Therefore, install the Android API levels 16 to 25 on Android Studio.
- Open Android Studio.
- Click SDK Manager.
- Click the SDK Platform tab and select the 16 and 25 API levels.
Example:
- Click Apply.
Open the
build.gradle
file, and configure the parameters given below under thedebug
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\""
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.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 theALLOW_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
andCOSU_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.
- Download or clone the
devicemgt-nfc-provisioning-android
from GitHub. 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
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 '='
Open the
build.gradle
file, and configure theDEFAULT_HOST
parameter that is under thedebug
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.
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/Colombolocale
The language used. Android only recognizes specific languages. Therefore, make sure to add a language that is already specified.
Example: en_USencryption
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 appbuild.gradle
file and configure thePUSH_KIOSK_APP
property that is under thedebug
variant as follows:buildConfigField "boolean", "PUSH_KIOSK_APP", "true"
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.
- 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
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.
- Tap Install on your device to finish installing the application.
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:
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.
NFC bump your device and the kiosk device.
Not sure what to do?
Bring the devices close to each other and tap them.
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.
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.
Navigate to the App Store using the following URL:
https://<IoT_HOST>:9443/store
Sign in using your username and password.
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:
- Select Instant install, and click Yes.
- 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. - 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.
- Manage the system updates COSU devices by publishing a policy on them. For more information, see Adding a System Update Policy for COSU Devices.