Remote Control for Android Devices

The remote control feature allows administrators to troubleshoot devices that are enrolled with WSO2 IoT Server using the device management console. This feature is used to create a remote session, remotely control, send adb shell commands, view the device logs, and view the screen of an Android device.

Let's take a look at how you can start using it.

Create a remote session

Follow the steps given below to create a remote session between the device and WSO2 IoT Server:

1. Start WSO2 IoT Server's core profile, which corresponds to the WSO2 Connected Device Management Framework (WSO2 CDMF) profile.
   
2. Access the device management console: https://<IOTS_HTTPS_HOST>:9443/devicemgt
For example: https://localhost:9443/devicemgt
3. Sign in as an administrator. By default, the username is admin and the password is admin.
4. Click View under Devices.
   
   You are navigated to the page that lists out all the devices that are enrolled with WSO2 IoT Server because you have administrator privileges.
5. Click on the device you want to start the remote session.
6. Click the Remote Session tab.
   
7. Click Connect to Device to start the remote session with the device. 
   Once the server connects to the device, you see the screen given below:
   
8. To stop the remote sharing session, click Close Session.

Send adb shell commands

Follow the steps given below to troubleshoot the device using adb shell commands:

1. Set up a remote session between your device and WSO2 IoT Server.
2. Click Shell.
3. Write the shell command and press the Enter key.
   For example, if you want to get the CPU and memory usage of the device, use the top adb command
   Sample output:
   

View device logs

Logcat displays messages in real time and keeps a history so you can view the old messages. Follow the steps given below to view the device logs.

1. Set up a remote session between your device and WSO2 IoT Server.
2. Click Logcat.

View the device screen

1. Set up a remote session between your device and WSO2 IoT Server.
2. Click Screen Share > Start.
   
3. A message is sent to the device asking the device owner to share the screen with WSO2 IoT Server. The device owner needs to accept this message.
   Once accepted, the administrator is able to view the device's screen, monitor how the device owner users the device, and troubleshoot the device.
   
4. Click Stop to stop viewing the screen of the device.

Carry out actions on the device

Viewing the screen of the device alone does not help you to solve the issue. You need to be able to carry out actions on the shared screen to successfully troubleshoot the device. Follow the steps given below to try it out:

1. Enable the Android System Service Applications.
   
   1. Build the system service application.
      1. Download the source code.
      2. The system service app can not be built via the usual Android developer Software Development Kit (SDK), as it requires access to developer restricted APIs. Therefore, you need to replace the existing android.jar file that is under the <SDK_LOCATION>/platforms/android-<COMPILE_SDK_VERSION> directory with the explicitly built android.jar file that has access to the restricted APIs. You can get the new jar file using one of the following options: 
         

         • Download the Android Open Source Project (AOSP) and build the source code to get the jar file for the required SDK level.

         • Use a pre-built jar file from a third party developer. You can find it here.

           Make sure to use the jar file that matches the compileSdkVersion of the WSO2 Android agent. The current compileSdkVersion is 25.

      3. Open the system service application source code via Android Studio and clean build it as a usual Android application.

   2. Sign the application via the device firmware signing key. If you don’t have access to the firmware signing key, you have to get the system application signed via your device vendor. 

      For more information of singing the system service, see Signing Your Applications.

   3. Install the system service application by following any of the methods given below:

      •  If you have your own firmware, the system service application is available out of the box with your firmware distribution.

        1. Copy the signed system service APK file to the /system/priv-apps directory of the device. 

        2. When the device boots or restarts for the first time, it automatically installs the application as a system application.

      • Install the system service application externally via an Android Debug Bridge (adb) command.

        For more information on how this takes place on WSO2 IoTS, see Configuring the service application.

   4. Enable the system service invocations through the WSO2  Android Agent application. 

       Click here for more information on cloning the Android agent.

      1. Clone the cdmf-agent-android GIT repository. This is referred to as <ANDROID_AGENT_SOURCE_CODE> throughout this document.

         https://github.com/wso2/cdmf-agent-android.git -b <ENTER_THE_VERSION>

         Check the WSO2 IoT Server and Agent Compatibility and find out what branch of this repo you need to clone.

      2. Open the client folder that is in the <ANDROID_AGENT_SOURCE_CODE> via Android Studio.

      Make sure to sign the Android agent using the same device firmware signing key that was used to sign the System Service Application, else you run into security exceptions.

   1. Navigate to the Constants.java class, which is in the org.wso2.iot.agent.utils package and configure the SYSTEM_APP_ENABLED field as follows:

       public static final boolean SYSTEM_APP_ENABLED = true;

   2. Rebuild the Android agent application.
   5. Install the Android agent you just built to your mobile device.
      You need to copy the APK to you device and install it. For more information on installing the Android agent, see Registering an Android device. Follow the steps from step 6 onwards.

2. Restart or start WSO2 IoT Server's core profile, which corresponds to the WSO2 Connected Device Management Framework (WSO2 CDMF) profile.
3. Access the device management console: https://<IOTS_HTTPS_HOST>:9443/devicemgt
   For example: https://localhost:9443/devicemgt
4. Sign in as an administrator. By default, the username is admin and the password is admin.
5. Click View under Devices.
   
   You are navigated to a page that lists out all the devices that are enrolled with WSO2 IoT Server because you have administrator privileges.
6. Click on the device you want to start a remote session.
7. Click the Remote Session tab.
8. Click  Screen Share > Start.
   
9. Click on the applications you want to open or the configurations you want to enable using the mouse.
10. Click Stop to stop viewing the screen of the device.