projecting-collect.rst

Projecting ODK Collect onto another screen

This guide helps the users to project ODK collect onto a screen. There are various methods available to do this, some of the methods are discussed below:

Using Vysor

Vysor is an extension for the Google Chrome browser that connects to an app on your smartphone. This extension enables you to control your phone from your PC or Mac using the mouse/trackpad and keyboard.

Before proceeding further make sure USB Debugging mode is enabled:

Enable USB Debugging Mode on Android

1. Go to :menuselection:`Settings`, choose :guilabel:`About phone`.
2. Scroll down and tap :guilabel:`Build number` seven times.

3. Go back to :menuselection:`Settings` and there you will find :guilabel:`Developer options` in the menu.

4. Scroll down and enable :guilabel:`USB debugging` mode.

5. Confirm the action when prompted.

Note

Windows users should make sure that they have downloaded Universal ADB Drivers.

Follow the instructions given below to use Vysor:

1. Make sure you have Google chrome installed, if not download it from here.
2. Download Vysor extension.
3. Click on :guilabel:`Add To Chrome`

4. Confirm your action by clicking on :guilabel:`Add app`.

Warning

On Windows, You may get an error WebGL is not supported

To fix this, follow the procedures given below:

First, we need to enable hardware acceleration:

1. Go to chrome://settings, scroll down and click on :guilabel:`Advanced`.

2. In the System section, ensure the Use :guilabel:`hardware acceleration when available` is enabled. You'll need to relaunch Chrome for any changes to take effect. Click on :guilabel:`RELAUCH`

3. Then, we need to enable WebGL, go to chrome://flags, scroll down and search for WebGL 2.0. From the drop-down list choose :guilabel:`Enabled`.

Now you can return to Vysor extension and install it again.

5. After adding the extension, you would be able to see it in the chrome toolbar, if it is not visible there go to chrome://apps and you would be able to see there.

6. Launch the extension and connect your phone through USB.

7. Click on :guilabel:`Find Devices`, select your device and click on :guilabel:`Select`.

8. After clicking :guilabel:`Select`, Vysor would be automatically downloaded to your phone, and you will be able to see your phone screen.

9. Click on the Collect app and there you go, you have successfully projected your phone screen.

Using Android Studio

Android Studio is the official IDE for Android. It provides tools for building apps for every type of Android device. Android Emulator can be used to test your app virtually on any Android device configuration.

Follow the procedures given below to run your app on the emulator:

1. Download Android Studio with SDK according to your platform.
2. Here is a tutorial on how to set up Android Studio according to different platforms.
3. After installing, launch Android Studio and click on :guilabel:`Start a new Android Studio project` or if you have an existing project click on :guilabel:`Open an existing Android Studio project`.

4. To create a new project follow further steps but if you have an existing project skip to the step 9.
5. Choose your project location and fill out the :guilabel:`Application name` and click on :guilabel:`Next`.

6. Select the :guilabel:`Phone and Tablet` option and choose your :menuselection:`Minimum SDK`. Click on :guilabel:`Next`.

7. Select an Activity, Empty Activity is preferable. Click on :guilabel:`Next`.

8. In Customize the Activity window, don't change the default options and click on :guilabel:`Finish`.

9. After few minutes, you will be able to see the Android Studio main window, click on icon, alternatively, you can click on :menuselection:`Tools` then select :guilabel:`Android`, from the drop-down menu select :guilabel:`AVD Manager`.

10. If you are an existing user list of all virtual devices would appear on the screen, to create a new virtual device, click on :guilabel:`+ Create Virtual Device...`

11. In the Select Hardware window, choose a device definition for your virtual device. I have chosen :guilabel:`Nexus 5`, click on :guilabel:`Next`.

12. Select a system image, I have chosen Lollipop version.Click on :guilabel:`Next`.

13. Enter your :guilabel:`AVD Name`, choose startup orientation and click on :guilabel:`Finish`.

14 Now you would be able to see your virtual device in Android Virtual Device Manager. Click on to run your Android emulator.

Note

Please wait for some time as Android emulator takes very long time to start.

15. After the emulator is started, you would be able to see the screen of your emulator. :

16. Now click on to see the location of Android SDK.

17. Open the terminal and move to the platform-tools of the SDK directory.

$ cd platform-tools

18. Copy the :file:`collect.apk` into :file:`platform-tools` folder. You can download the apk file from here.
19. Type the following command to see the list connected devices:

$ adb devices

You should be able to see the emulator along with its port number, e.g emulator-5554, Here 5554 is the port number. If the emulator is not present in the list, restart the emulator.

To install apk file, in the emulator type the following command:

$ adb install collect.apk

If the command is successfully executed, you will find your file in the launcher of your emulator.

Using Command Line

You can also run the emulator using command line. Follow the steps given below to start your emulator using the command line:

Note

If SDK installation has been put in another drive or folder instead of in its default location of $USER_HOME or $HOME. Make sure you have set the environment variables according to that. In the command line type the following command to set environment variables.

set ANDROID_SDK_ROOT=path\sdk\

1. Open the terminal and move to the :file:`emulator` folder of the SDK directory.

$ cd emulator

2. For the list of available virtual devices, type the following command:

$ emulator -list-avds

Tip

If you are not able to locate :file:`emulator.exe` file in :file:`SDK` folder. Type the following command to know the location of the file:

$ which emulator

On Windows:

> where emulator

3. Use :command:`emulator` to start the emulator. Here avd_name is the name of Android virtual device that you have created.

$ emulator -avd avd_name

Note

1. You can use :command:`sdkmanager` command to update, install, and uninstall packages for the Android SDK. This method is not recommended as it is not user-friendly and also takes time.

   To create an emualtor you need to download system image for a particular API level.

$ sdkmanager --verbose "system-images;android-19;google_apis;x86"

• The :option:`--verbose` option or :option:`-v` option shows errors, warnings and all messages.
• system-images;android-19;google_apis specifies the system image package for the Android virtual device.
• android-19 specifies the API level. You can choose different API level if you want.

2. To create and manage Android Virtual device from the command line, you can use :command:`avdmanager`.

   After downloading system image, you can use the following command to create an emulator.

$ avdmanager -v create avd --name testAVD -k "system-images;android-19;google_apis;x86" -g "google_apis"

• The :option:`create avd` option creates a new Android virtual device.
• :option:`--name` option is a required option which is used to specify name of the AVD. Here, the name of the AVD is testAVD.
• The :option:`-g` specifies the sys-img tag to use for the AVD.
• :option:`-k` specifies package path of the system image for the AVD.

.. seealso::

  You can also use `Genymotion <https://www.genymotion.com/>`_ as an alternative as it is very fast as compared to custom android emulators. It is also easy to use and configure, and it is available free of cost for personal use.