Getting started

Here you can find all the information for getting started: how to set up your development environment and how to run the application in emulator and device.

Environment setup

1. Download and install ADT Bundle

Download the latest Android Developer Tools (ADT) Bundle including the Android SDK from http://developer.android.com/sdk/index.html. Install the software by following the instructions at http://developer.android.com/sdk/installing/bundle.html. Note that the website automatically detects your OS and provides the appropriate installation package.

Note that Eclipse IDE, which is included in the ADT Bundle, requires JDK to work (JRE alone is not sufficient). Make sure that the bit version of the bundle matches the JDK, i.e., both need to be either 32-bit or 64-bit. Having different versions will result in an error. The general recommendation is to install the latest JDK version, but depending on the host platform some compatibility problems may arise. The supported JDK versions of each Eclipse IDE are listed in the Eclipse project release notes, which can be found at www.eclipse.org.

2. Install required packages with Android SDK Manager

Launch the Android SDK Manager. The manager application can be launched from the IDE or the command line. Launching the manager from the command line:

Windows

<Android SDK installation path>\SDK Manager.exe

Linux and Mac

<Android SDK installation path>/tools/android sdk

Tip: If you prefer using the command line tools, add the paths to the executable tools into environment variables so that you don’t have to explicitly define the path when using a tool. A guide demonstrating how to do this for each host platform can be found here.

To launch the Android SDK Manager in IDE: first, launch Eclipse. Then, in Windows and Linux, select Window -> Android SDK Manager (figure 1). In Mac, locate the Android SDK Manager icon from menu on the top of the IDE window (tooltips are provided) and click the icon to open (figure 2).

Figure 1. Android SDK Manager and Android Virtual Device Manager can be launched under Window menu in Windows and Linux.

Figure 1. Android SDK Manager and Android Virtual Device Manager can be launched under Window menu in Windows and Linux.

Figure 2. Location of launcher icons in Eclipse in Mac.

Figure 2. Location of launcher icons in Eclipse in Mac.

Install the following packages:

  • Tools
    • Android SDK Tools*
    • Android SDK Platform-tools*
  • Extras
    • Intel x86 Emulator Accelerator (emulator prerequisite for x86 system images)

*) Installed by default, but update to the latest version is recommended. You may run into problems with the environment with outdated packages.

In addition, for Nokia X2 install the packages for Android 4.3 API 18:

  • Android API version 4.3 API 18
    • SDK Platform
    • ARM EABI v7a System Image (emulator prerequisite for ARM system images)
    • Intel x86 Atom System Image (emulator prerequisite for x86 system images)

For Nokia X/X+/XL install the packages for Android 4.1.2 API 16:

  • Android API version 4.1.2 API 16
    • SDK Platform
    • ARM EABI v7a System Image (emulator prerequisite for ARM system images)
    • Intel x86 Atom System Image (emulator prerequisite for x86 system images)

The packages above are required by the Nokia X software platform development environment. Note that there is no need to uninstall any packages that are installed by default.

Important:

  • For faster emulator experience, it is recommended to install the Intel HAXM executable following the instructions given here. Note, that Intel HAXM works only with Intel Atom (x86) AVD (see the Setting up the emulator section for more details).
  • To use x86 emulator on Microsoft Windows 8.1 or Mac OS 10.6 and later, ensure that the respective OS specific Hotfix is installed from the IntelĀ® Hardware Accelerated Execution Manager download page.
Figure 3. Required AOSP packages installed with Android SDK Manager.

Figure 3. Required AOSP packages installed with Android SDK Manager.

3. Install Nokia X specific packages

You can install the Nokia X specific packages with an installer. The instructions for using the installer are provided in the download package.

4. Setting up the emulator

To set up the emulator, we need to create a new Android Virtual Device (AVD). Like installing packages, this can also be done either from the Eclipse IDE, or by command. From Eclipse: in Windows and Linux, select Window -> Android Virtual Device Manager (figure 1). In Mac, locate the Android Virtual Device Manager icon from the menu and click the icon to launch the manager (figure 2). If the menu is not visible, go to Window -> Show Toolbar. Launching the AVD manager from the command line can be done with command:

Windows

<Android SDK installation path>\tools\android avd

Linux and Mac

<Android SDK installation path>/tools/android avd

Open the Device Definition tab, select Nokia X by Nokia or Nokia X2 by Nokia from the list of devices and click Create AVD button (see figure 5).

Figure 5. Android Virtual Device Manager, Device Definitions tab.

Figure 5. Android Virtual Device Manager, Device Definitions tab.

Provide a name for the AVD, for example “AVD_for_Nokia_X” or “AVD_for_Nokia_X2”. Also, ensure that the target of the AVD is:

  • Nokia X software platform 2.0 (Nokia) - API Level 18 for Nokia X2
  • Nokia X software platform 1.1 (Nokia) - API Level 16 for Nokia X/X+/XL

It is recommended to set a SD card and check Use Host GPU since those are required to run HERE applications, change the IMEI and MCC/MNC number of the emulator, and to run Xpress Browser (figures 6 and 7). Select the desired AVD from the CPU/ABI drop-down and select the Skin option as Skin with dynamic hardware controls. Once you are happy with the settings click OK to create the virtual device. Note that you can change the settings of the AVD later.

Figure 6. Creating Nokia X2 Android Virtual Device.

Figure 6. Creating Nokia X2 Android Virtual Device.

Figure 7. Creating Nokia X Android Virtual Device.

Figure 7. Creating Nokia X Android Virtual Device.

To verify that the emulator works, you can launch it by going back to Android Virtual Devices tab in Android Virtual Device Manager, selecting the created AVD and clicking the Start button (figures 7 and 8). You can also launch the AVD from the command line:

Windows

<Android SDK installation path>\tools\emulator -avd AVD_for_Nokia_X2

Linux and Mac

<Android SDK installation path>/tools/emulator -avd AVD_for_Nokia_X2

(Syntax: emulator -avd <the name of the AVD to launch>)

Figure 8. Android Virtual Device ready to be started.

Figure 8. Android Virtual Device ready to be started.

Note: While launching the Intel Atom x86 AVD, if you get the following error message, it means that the Intel HAXM executable is not installed. Refer to step 2 to install the executable. However, this does not affect the working of the AVD in any manner.

Figure 9. Error message.

Figure 9. Error message.

Benefits and limitations of using the x86 AVDs

Here are some of the benefits and limitations of using the x86 AVDs:

Benefits

  • 80% faster first time emulator start up.
  • 80% faster subsequent emulator start-ups.
  • Enhanced performance for apps using hardware acceleration, such as Browser, HERE maps and so on.

Limitations

Apps using native Android code must be re-built for the x86 target. Also, prior to deploying such apps, they must also be re-built and verified for the ARM target.

Using the Snapshot feature

Using the snapshot feature allows the emulator state to be persistent between emulator executions. This will also make the emulator start up faster. Unfortunately, GPU emulation cannot be used together with this feature and thus, you cannot work with HERE Maps, if this feature is enabled. However, if you don’t need GPU emulation, you can use the feature with no problems.

To enable and test the Snapshot feature, do the following:

  • Select the Snapshot setting in the Emulating Options when creating or editing the AVD (figure 6) and launch the emulator.
  • On the first launch, deselect Launch from snapshot and select Save to snapshot.
  • Wait for the emulator to start and when the emulator is in a state you want (e.g., Device is in Airplane mode), shut down the emulator. Shutting down will take some time, because a snapshot is created.
  • Start the emulator again, but this time select Launch from snapshot and deselect Save to snapshot. The emulator is launched a lot faster now and it will be in the state where the snapshot was created (e.g., Airplane mode).

Device setup

The use of Android Debug Bridge tool (ADB) is required, when following these instructions. The use of the tool is more convenient, when the path to the tool is set to the PATH environment variable. ADB provided with the standard Android SDK and it is located in folder <Android SDK path>/sdk/platform-tools on all platforms.

Enabling USB debugging

In order for the ADB tool to recognise your device, you need to enable the USB debugging on the device by following these simple steps:

  1. Launch device settings.
  2. On Nokia X software platform 2.0 you will need to enable developer options by navigating to Settings -> About phone and quickly tapping the Software version entry at the bottom of the list 5 times. After tapping it you will get a toast notification telling you that “You are now a Developer”. Now you should be able to see Developer options item in the settings menu.
  3. Tap Developer options in the System section.
  4. Switch on developer options and tap OK in the query dialog shown.
  5. Enable USB debugging in the Debugging section and tap OK in the query dialog shown.

Your device has now USB debugging enabled.

Linux specific steps

To configure ADB on Linux follow the steps below:

  1. Edit /etc/udev/rules.d/51-android.rules (or create the file, if it does not exist) and add:

    SUBSYSTEMS=="usb", ATTRS{idVendor}=="0421", MODE="0666", OWNER="<username>"

    (OWNER is optional.)

  2. Restart udev service with command:

    $ sudo service udev restart

  3. Go to <Android SDK installation path>/tools and run command:

    $ sudo ./android update adb

  4. Edit /home/<user>/.android/adb_usb.ini and add 0x0421. If the file adb_usb.ini does not exist, create one.
  5. Kill adb with command:

    $ adb kill-server

  6. Start adb with command:

    $ adb start-server

  7. To see if the device is being listed, run command:

    $ adb devices

    • If the device is not listed, try reconnecting the USB cable.

Mac OS specific steps

To configure ADB on Mac OS follow the steps below:

  1. Create or edit file /Users/<user>/.android/adb_usb.ini and add line:

    0x0421

    (Note, In Finder, hidden files are not shown by default. Open Terminal to edit/create file and type nano /Users/<user>/.android/adb_usb.ini. After editing, save with ctrl-o and exit with ctrl-x.)

  2. Kill adb with command:

    $ adb kill-server

  3. Start adb with command:

    $ adb start-server

  4. To see if the device is being listed, run command:

    $ adb devices

Windows specific steps

Step 1. Device driver installation

The device driver installation is required by the ADB utility and for deploying applications to the device. Installing the drivers is needed only once. You need to have the driver files stored locally (on your computer or media attached) before proceeding with the following steps. In addition, enable USB debugging before installing the drivers.

The USB drivers are available via the SDK Manager under extras in Nokia X USB Driver package. When installed, the drivers can be found in <Android SDK installation path>\extras\nokia\usb_driver folder.

  1. Open Control Panel. Then locate and open Device Manager.
  2. Make sure you have the device turned on and connected via USB.
  3. Check the device list in the Device Manager for new items. It should contain at least one item, that starts with a name Nokia_X followed by the RM number, under Other devices (see figure 1).
  4. Right click the item and select Update Driver Software (figure 1).

    Figure 1. Updating the device driver software.

    Figure 1. Updating the device driver software.

  5. Select Browse my computer for driver software (figure 2).

    Figure 2. Browse the computer for the drivers.

    Figure 2. Browse the computer for the drivers.

  6. Click Browse, navigate to the <Android SDK installation path>\extras\nokia\usb_driver folder and when you have the path set, click Next.
  7. Accept the security prompt by clicking Install (figure 3).

    Figure 3. Security prompt informing that the driver is signed by Nokia.

    Figure 3. Security prompt informing that the driver is signed by Nokia.

  8. After the installation, close the dialog.

    Figure 4. USB drivers successfully installed.

    Figure 4. USB drivers successfully installed.

Note: If you see an error message saying that the software is blocked from starting or the software does not support your OS, it is likely that Windows has tried to install the wrong version of the driver, e.g. 32-bit version instead of 64-bit. It is recommended to start over by uninstalling the wrong drivers and then selecting the driver files manually.

After a successful installation you should have the following items visible in Device Manager:

  • Nokia Device
    • Nokia Composite ADB Interface
  • Portable Devices
    • Phone model, e.g. “Nokia X”

Step 2. Configuring ADB

  1. Edit the file C:\Users\<user>.android\adb_usb.ini and add line:

    0x0421

  2. Open command prompt (press Windows key + R and type “cmd”) and kill adb with command:

    adb kill-server

  3. Start adb with command:

    adb start-server

  4. To see if the device is being listed, run command:

    adb devices

    • If the device is still not listed, you can also try connecting it to the other USB ports.

    Note: The adb_usb.ini file might be deleted during the process of uninstalling incorrectly installed device drivers. After uninstalling manually the device on Windows, please ensure that the adb_usb.ini is located in the path as described above and that it is not empty.

For more details, see the SDK device setup page.

Uninstalling drivers

In case you installed the wrong device drivers, for example 32-bit instead of 64-bit, uninstall the drivers and start over. Devices with missing, incorrect, or non-functional drivers are displayed with a yellow warning sign on top of the list item icon similarly as in figure 1. To uninstall a driver, follow the following steps:

  1. Right-click the device, whose drivers to uninstall, in the Device Manager window and select Uninstall.
  2. In the Confirm Device Uninstall dialog, check Delete the driver software for this device and click OK.

Before attempting to re-install the drivers, please repeat the uninstall process for all instances of incorrectly installed devices associated with the Nokia X device. You might need to disconnect and reconnect the device and check that there are no associated items left with invalid drivers.

Running an application in emulator and on device

If you are porting an existing application, import your project in the Eclipse IDE. In case you want to start from scratch, you can create a new project.

Creating a new project

Creating a new Android application project in Eclipse is done as follows:

  1. Select New -> Android Application Project from File menu.
  2. In New Android Application window:
    1. Enter the application name, the project name, and the package name, for instance:
      • Application Name: My App
      • Project Name: MyApp
      • Package Name: com.example.myapp
    2. Set the Minimum Required SDK based on your application requirements. This setting can be changed later.
    3. To ensure the compatibility with Nokia X software platform 1.0, set the Target SDK and Compile With to API 16: Android 4.1 (Jelly Bean). However, if you are certain that your app requires the very latest features in API level 18, set the values to API 18: Android 4.3 (Jelly Bean), which is the supported API level of Nokia X software platform 2.0.
    4. Select the Theme (can be changed later).
    5. Click Next.
  3. Configure the project and click Next. The default configuration is usually OK and the configuration can be modified later.
  4. Define your launcher icon. If you have not yet created one, go with the default option. Finally, click Next.
  5. Select the Activity template (if you had Create activity selected for the configuration) and click Next.
  6. Set the Activity Name and layout and click Finish to create the project.

If the wizard fails to find the tools - you will be prompted with error message: “Unsupported template dependency: Upgrade your Android Eclipse plugin” - this is due to an Android Development Tools (ADT) issue. See the instructions for a workaround here.

Importing a project

Importing a project in Eclipse is done as follows:

  • Select Import from File menu (figure 1).
  • In the Import dialog, select Existing Android Code Into Workspace under Android and click Next (figure 2).
  • Browse to the root folder of the application to import and click Finish (figure 3).
Figure 1. Import option in File menu.

Figure 1. Import option in File menu.

Figure 2. Importing existing Android project.

Figure 2. Importing existing Android project.

Figure 3. Locate the project to import and click Finish.

Figure 3. Locate the project to import and click Finish.

Setting the run configurations

Open run configurations. In Eclipse, select Run -> Run Configurations… (see the figure below).

Figure 4. Opening Run Configurations.

Figure 4. Opening Run Configurations.

If you have an existing launch configuration for the project, select it from the list under Android Application. If you have no launch configurations defined, create a new one by selecting Android Application (the item becomes highlighted) and clicking the New launch configuration icon (see figure 5). Then, select the project for the configuration by clicking the Browse… button on the right. Finally, name the launch configuration as you please.

Figure 5. New launch configuration icon button.

Figure 5. New launch configuration icon button.

Open the Target tab and select the checkbox for the desired emulator target on the right (see the figure below).

Figure 6. Selecting the emulator for project.

Figure 6. Selecting the emulator for project.

Finally, click Apply. If you then want to run the application right away, click Run. If you just want to save the configuration and run the app later, click Close. Accept any prompts shown to save the configuration.

Note: If you alternate often between using device and emulator, it is better to select Always prompt to pick device.

  • If you have imported BasicMapSolution, ExtendedBasicMapSolution or SimpleRoutingSolution, ensure that you perform the following additional steps:

    1. Right-click on the project and select Properties > Java Build Path > Libraries tab.

    2. Click Add External JARs and select <android-sdk-install-path>/extras/nokia/nokia_x_services/libs/here/com.here.android.sdk.jar and click OK.

    3. Make sure that the library is not exported to JAR, i.e. the check box is not checked in Order and Export tab.

      Figure 7. Adding HERE libraries

      Figure 7. Adding HERE libraries

Running an application

There are several ways to run the application. You can, for instance, right click the project name in Package Explorer and select Run As -> Android Application (figure 8). This will run the app as per the currently set run configurations for the project.

Figure 8. Running the application in IDE.

Figure 8. Running the application in IDE.

If you did select Always prompt to pick device on the Run Configurations Target tab and you have two or more devices set up (virtual or physical), you will be prompted to select the device. If you have a physical device connected and configured, you can run the app on the device by selecting it from the Android Device Chooser and clicking OK (figure 9).

Figure 9. Select the connected device from Android Device Chooser.

Figure 9. Select the connected device from Android Device Chooser.

The application should now be installed and launched on the device.