Setting Up Single-Purpose Devices

In this document, you will take a look at how to set up and use Corporate-Owned, Single-Use (COSU) 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 COSU 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 COSU 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 is 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 COSU 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/COSU devices.

Step 1: Customizing the Android Agent

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

1. Replace the android.jar file that is in the <ANDROID_STUDIO>/<SDK location>/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 23. Therefore, install the Android API levels 16 to 23 on Android Studio.
   1. Open Android Studio.
   2. Click SDK Manager.
      
   3. Click the SDK Platform tab and select the 16 and 23 API levels.
      Example:
      
   4. Click Apply.

5. Open the build.gradle file, and configure the parameters given below.

   DEFAULT_OWNERSHIP	Define COSU as the value.
   DEFAULT_HOST	Define <NETWORK_IP>:8280 as the value. All devices must be connected to the same network.

   // 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 Google Android-NfcProvisioning application

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

1. Download or clone the Android NfcProvisioning Sample 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.

   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 <android-NfcProvisioning>/Application/java/com/example/android/nfcprovisioning/NfcProvisioningFragment file, and add the following attributes under the public void onTextChanged(int id, String s) method.

   mProvisioningValues.put(DevicePolicyManager.EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION, "THE PATH OF APK FILE YOU HOSTED IN STEP 1.7.");
   mProvisioningValues.put(DevicePolicyManager.EXTRA_PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM, "CHECKSUM VALUE OF THE AGENT YOU GOT IN STEP 2.3.");

   Example:

   mProvisioningValues.put(DevicePolicyManager.EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_DOWNLOAD_LOCATION, "https://github.com/shavidissa/android-for-work-COSU/blob/master/client-debug.apk?raw=true");
   mProvisioningValues.put(DevicePolicyManager.EXTRA_PROVISIONING_DEVICE_ADMIN_SIGNATURE_CHECKSUM, "bgEGfd2vik7OBItxjU7TR7JNXmc");

5. 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. Open the application once it's installed and enter the following details:

   Some of the details will be filled automatically.

   • [PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME] - The package name of the WSO2 IoT Server Android agent, which is org.wso2.iot.agent.
   • [PROVISIONING_LOCALE] - The Locale that the device will be set to. This is filled in by default.
   • [PROVISIONING_TIME_ZONE] - The time zone AlarmManager that the device will be set to.
   • PROVISIONING_WIFI_SSID] - The SSID of the WiFi network that should be used during NFC device owner provisioning for downloading the mobile device management application. 
   • [PROVISIONING_WIFI_PASSWORD] - The password of the wifi network you are connected to.
   Example: 
   

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

Step 4: Installing the Android agent on the COSU device

1. NFC bump your device and the COSU device.

   Not sure what to do?

   Bring the devices close to each other and tap them. 

2. Click Encrypt data and confirm that you want to encrypt data on the COSU device.
   The device encrypting process will start. It will take a few minutes to complete. 

3. Once the device restarts, it 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.

4. The WSO2 Android agent downloads on to the COSU device.

   How does this happen automatically?

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

5. Enter the server address based on your environment, in the text box provided. A confirmation message will appear.

   • Developer Environment - Enter the server IP as your server address.
     Example: 10.10.10.123:8280

   • Deployment Environment - Enter the domain as your server address.

     The Android Agent app's default port is 8280. If you are using any other port, the server address should state the new port in the following format: www.abc.com :<PORT>
     For example, if the port is 8289 the server IP is as follows: www.abc.com:8289

   
6. Tap Yes to continue.
   
7. Enter your details and tap Register. A confirmation message will appear.
   

   • Username - Enter your WSO2 IoTS username.

   • Password - Enter your WSO2 IoTS password. 

   • Domain - Enter the domain only if the server is hosted with multi-tenant support.
   • Ownership type - Select the corresponding device ownership option. This will customize the device management behavior accordingly.
     
     • BYOD - Bring your own device.
     • COPE - Corporate owned personally enabled.
   
8. Tap Yes to continue.

   • If you select BYOD go to step 13 - You will be shown a policy agreement, which you can either accept or reject.

     You will get access to WSO2 IoTS only if you accept the policy agreement.

     

   • If you select COPEgo to step 17 - As it's a corporate owned device, you will not be shown a policy agreement. You will have to adhere to the company policy.
     
9. Read the tenant policy agreement, and tap Agree to accept the agreement.  

10. Tap ALLOW to allow the WSO2 Android agent to make and manage phone calls, access photos, media, and files and access the device location respectively.

    You will get this message only if your Android OS is Marshmallow (6.0) or above.

    Example:

    

11. Set a PIN code of your choice with a minimum of 4 digits. The PIN code will be used to secure your personal data. Thereby, the IoT server will not be able to carry out critical operations on your personal data without using this PIN. 
    Example: If the device management admin needs to wipe your device or remove data from the device, he/she can not directly wipe it without the PIN code. You have to provide the PIN code to get your device wiped or you can log into the device management console and wipe your device by entering the PIN code. A confirmation message will appear.

    You will be prompted to provide a PIN code only if your device is a BYOD device.

    

12. Confirm the PIN and click OK to continue.
    
13. Tap ACTIVATE to enable the WSO2 agent administrator on your device. A confirmation message will appear after enabling the device admin.
    

14. You have now successfully registered your Android device. If you wish to unregister the registered device, click Unregister.
    

     Click here for more information on how to uninstall the Android agent.

    Follow the instructions below to uninstall the Android agent app:

    1. Open the Android agent application and click Unregister.

    2. In Settings, tap Applications or Application Manager on your device. This may differ based on your device. If your device has the Applications menu, tap Manage Applications, otherwise directly move to step 3.

    3. Tap WSO2 Agent to select the Android agent app.

    4. Tap Uninstall.

Step 5: Installing the required applications on the COSU device

One the Android agent is installed on the COSU 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 COSU 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.

   

4. Select Instant install, and click Yes.
   
5. Click on your 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. Tap Install on your device to finish installing the application.
   

What's next?

• Once you are done using the device, device administrators can enterprise wipe the device. 

   Click here to expand...

  1. On the device management console home page, click View under Devices.
  2. Click on the COSU device, and click on the enterprise wipe operations that is under Device operations.
• Manage the system updates COSU devices by publishing a policy on them. For more information, see Adding a System Update Policy for COSU Devices.