Knowledge Base & Forum/Forums/General Information

Marmalade Quick Start

ghoffer
posted this on August 29, 2012, 12:54 PM

Introduction

This guide helps Marmalade developers sideload (directly install) apps to a NOOK device. Get more NOOK info at nookdeveloper.com. Information on Marmalade is available from madewithmarmalade.com.

Important You need to complete all steps necessary to get your computer to communicate with your NOOK device BEFORE running the Marmalade Deploy Tool.

Windows Users We recommend that you only install the 32-bit JDK for use with Marmalade app development. The 64-bit JDK currently has an error in Marmalade where files are incorrectly signed, which results in a certificate failure when you use the adb install command to sideload your app to a NOOK device. For more information on the error see Android: apparent SDK problem with MWM-splash-540.jpg prevents app installation. The Marmalade error number is MAINT-1069.

Task Checklist

Use the following checklist to verify the steps in this guide.

TaskDescription
Framework Limitations and Software Requirements Verify framework limitations and software requirements.
(Optional) Install NOOK SDK Add-on If your app uses the Barnes & Noble SHOP Details API, DRM API, or the Wallpaper API, download and install the NOOK SDK Add-on.
Set the PATH Variable Run Android SDK commands from a command line
Sideloading Apps Starts the process of installing an app on a NOOK device
Provision a NOOK Device Enables a NOOK device to communicate with the Android SDK
Add NOOK Device ID for ADB Access Ensures that the Android Debug Bridge (ADB) and communicate with the Android SDK
Use ADB to Access a NOOK Device Communicating with the NOOK device
Use Marmalade to Sideload an App Use Marmalade to create an app package and install (sideload) it to your NOOK device
Handle the NOOK Button in Marmalade Explains how to handle the NOOK button.

Back to Top

Software Requirements

See Software Requirements in the NOOK Developer Start Up Guide.

Back to Top

Working With NOOK Devices

The sections that follow help you work with NOOK devices.

(Optional) Install NOOK SDK Add-on

If your app uses the Barnes & Noble SHOP Details API, DRM API, or the Wallpaper API, download and install the NOOK SDK Add-on.  Note  NOOK Color & NOOK Tablet use the NOOK Wallpaper API in the NOOK SDK Add-on. NOOK HD & NOOK HD+ use the Android WallpaperManager API.

Important  Before installing the NOOK SDK Add-on, install Java and the Android SDK. Android only supports Java Development Kit (JDK) 1.6.

To download and install the NOOK SDK Add-on, you use the Android SDK Manager, in which you provide the Barnes & Noble URL for where the SDK software resides. The Android SDK Manager fetches the software and prompts you through the steps required to install the SDK on your computer.

To install the NOOK SDK, first start the SDK Manager:

Windows:

  1. Click Start > All Programs > Android SDK Tools.
  2. Right-click SDK Manager and click Run as administrator - Important  Always run the Android SDK Manager as administrator. 

Mac OS:

  1. Open a Terminal (Finder > Go > Utilities > Terminal).
  2. Change directory to the tools directory where you unzipped the Android SDK software and type android

Both Windows and Mac:

  1. In the Android SDK Manager window, click Tools > Manage Add-on Sites.
  2. Click New in the Add-on Sites window:
  3. In the Add-on Site URL window, type one of the following URLs and click OK:

    NOOK HD & NOOK HD+

    http://su.barnesandnoble.com/nook/sdk/nook_hd_addon.xml

    NOOK Color

    http://su.barnesandnoble.com/nook/sdk/addon.xml

    NOOK Tablet

    http://su.barnesandnoble.com/nook/sdk/Nook_Tablet_addon.xml

  4. Click Close in the Add-on Sites window. Android SDK manager downloads the NOOK device add-on packages from the URL you specify.
  5. Verify the download from Android SDK Manager by scrolling down and looking for NOOK SDK under Android 4.0.3 (API 15), NOOK Tablet under Android 2.3.3 (API 10), or NOOKcolor under Android 2.2 (API 8).
  6. Click the checkbox for each package to instal.
  7. Click the Install button.
  8. In the Choose Packages to Install window, ensure that each NOOK package displays with a green check mark. If shown with a question mark, click Accept All and click Install.
  9. Verify that each NOOK package installs. If successful, Installed appears on the same line as the package name in the Android SDK Manager:

    Important  If Installed doesn't display and you're using Windows, ensure that you ran the SDK Manager as administrator. If not run as administrator, packages do not display as Installed even though all functionality appears to work.

Back to Top

Set the PATH Variable

Adding the SDK Tools folder paths to the PATH environment variable simplifies how you enter commands from the command line.

This section provides descriptions for Mac OS, Windows 7, and Windows XP.

Mac OS:

  1. Start a Terminal from Finder > Go > Utilities > Terminal.
  2. Update the PATH variable in the .bash_profile initialization file with the following command. 
    Important  Change <path> in this command to the path where you unzipped the Android software distribution file:

    echo -e '\nexport PATH=${PATH}:/Users/<path>/android-sdk-macosx/tools:/Users/<path>/android-sdk-macosx/platform-tools' >> ~/.bash_profile
  3. Quit the Terminal by typing Command+Q or clicking the dismiss button. The .bash_profile file is read when the Terminal starts, so it's important to restart the Terminal so the new PATH value is recognized.
  4. Start a new Terminal from Finder > Go > Utilities > Terminal.
    From the Terminal, start the SDK Manager by typing:   android

Windows 7:

  1. Click Start and right-click Computer > Properties.
  2. In the properties windows, click Advanced System Settings.
  3. On the Advanced tab, click Environment Variables.
  4. In the Environment Variables window:
    1. Double-click Path under System variables.
    2. Click in the Variable value field and press the End button on your keyboard to move the cursor to the end of the field. Add the following text to the end of the Path field. The starting semicolon is required to separate the new information from the existing information:

      ;C:\Program Files (x86)\Android\android-sdk\platform-tools;C:\Program Files\Android\android-sdk\tools

      If you installed the Android software in a non-default location, locate the folder, right-click the address bar, and click Copy address as text to get the folder name for the command.

      If you need to add the Java path to the Path variable, add one of these:
      For 64-bit Windows 7, add  c:\Program Files\Java\jdk<version>\bin
      For 32-bit Windows 7, add  c:\Program Files (x86)\Java\jdk<version>\bin

    3. Click OK to exit each window—Edit window, Environment Variables, and System Properties.
  5. Dismiss the Control Panel Home window.
  6. If you have a command prompt open, close it, and restart the command prompt to access the Android commands.

Windows XP

  1. Click Start and right-click My Computer and click Properties.
  2. Click the Advanced tab and Environment Variables.
  3. Scroll down and select the Path system variable and click Edit.
  4. Add the following to the end of the Path variable:

    ;C:\Program Files\Android\android-sdk\platform-tools;C:\Program Files\Android\android-sdk\tools

    If you need to add the Java path to the Path variable, add one of these:
    For 64-bit Windows XP, add c:\Program Files\Java\jdk<version>\bin
    For 32-bit Windows XP, add c:\Program Files (x86)\Java\jdk<version>\bin
  5. Click OK to exit each window—Edit window, Environment Variables, and System Properties.
  6. If you have a command prompt open, close it, and restart the command prompt to access the Android commands.

Back to Top

Sideloading Apps

You can sideload apps to your NOOK device after your device becomes visible to the Android Debug Bridge (ADB) command. Sideloading means manually installing apps to the NOOK device and then making the apps visible to the NOOK app user interface.

Quick Tip Attach your NOOK device to your computer using the USB cable. On an NOOK HD or NOOK HD+, first enable USB access: Click the Settings icon at the top bar of the device or launch the Settings app, click All Settings > Developer options > USB debugging. Click OK at the Allow USB debugging prompt. A check mark appears on USB debugging.

Try these commands from the command line:

  1. android update adb
  2. adb kill-server
  3. adb start-server
  4. adb devices
If the adb devices command lists the serial number of your NOOK device, skip to Install Apps on the Device and start sideloading. If the serial number doesn't display, continue to the next section in this chapter. The adb devices command should list the serial number and "device":

adb devices
List of devices attached
4242424242424242        device

>

Windows users: First Install Android Drivers before proceeding.

Back to Top

(NOOK Color and NOOK Tablet Only) Provision a NOOK Device

Note  You must have NOOK App Developer access before you can submit apps to Barnes & Noble. NOOK Color and NOOK Tablet developers also require NOOK App Developer status to gain access to a provision file that enables the NOOK device to communicate with the Android Debug Bridge (ADB) command.

NOOK HD & NOOK HD+ devices communicate directly with ADB without a provision file. On an NOOK HD or NOOK HD+, first enable USB access: Click the Settings icon at the top bar of the device or launch the Settings app, click All Settings > Developer options > USB debugging. Click OK at the Allow USB debugging prompt. A check mark appears on USB debugging.

The following procedures enable communication between a NOOK device and your computer.

  1. Plug the USB cable into your NOOK device and your computer.
  2. Power on your NOOK device and check for a bug icon in the lower left of the screen.
    If already provisioned, a bug icon displays in the lower left corner of your device. If this icon is present in the NOOK device, skip the remainder of this section.
  3. In Windows, if the NOOK device appears in the AutoPlay window, dismiss the AutoPlay window.
  4. Browse to http://nookdeveloper.com and log on to the NOOK Developer site.
  5. Click TOOLS & SERVICES at the top of the page.
  6. Click Developer Mode in the left navigation area of the page.
  7. Specify:
    1. Device Name - This can be any name. The name just lets you differentiate one device from another. Provisioning works with the serial number not the name.
    2. Serial Number - Printed on the inside of the SD card flap at the back of your NOOK device.
  8. Click Add Device - Note Adobe Flash is required to use the provision tool.
  9. Click Download Provision for your NOOK device.
  10. In Windows in the Save As window, select your NOOK device and click Save. In Mac, save the provision file in the root (lowest level) directory of your NOOK device.
    When provisioned, the bug icon appears in the lower left corner of your device.
  11. When done, eject the NOOK device. In Windows, click Start > Computer, right-click the NOOK device, and click Eject. In Mac OS, click the Eject icon in Finder.

Back to Top

Add NOOK Device ID for ADB Access

Add the NOOK device ID value of 0x2080 as the last line in the adb_usb.ini initialization file.

Note If the adb_usb.ini initialization file, doesn't exist, create the file in the .android folder.

Windows

  1. Click Start > All Programs > Accessories. Right-click Command Prompt and click Run as administrator. In Windows XP, click Run as and then choose The following user: Administrator and provide the administrator password.
  2. Type:  type "%USERPROFILE%\.android\adb_usb.ini"
    By default, %USERPROFILE% in Windows 7 is \Users\<username>\.
    In Windows XP, it's \Documents and Settings\<username>\
  3. If the last line is not 0x2080, type:
    echo 0x2080 >> "%USERPROFILE%\.android\adb_usb.ini"

Mac OS

  1. Click Finder > Go > Utilities > Terminal.
  2. Type:
    android update adb
  3. Type:
    cat ~/.android/adb_usb.ini

    The contents of the file should appear as:
    # ANDROID 3RD PARTY USB VENDOR ID LIST -- DO NOT EDIT.
    # USE 'android update adb' TO GENERATE.
    # 1 USB VENDOR ID PER LINE.
    0x2080
    
  4. If the last line is not 0x2080, type:
    echo -e '\n0x2080' >> ~/.android/adb_usb.ini

Back to Top

Use ADB to Access a NOOK Device

This section ensures that you can access a NOOK device using the Android Debug Bridge (ADB) command set.

  1. Plug your NOOK device into its USB cable and connect it to your computer.
  2. Power on the NOOK device to ensure that it's available for access.
  3. Remove any other Android devices from USB slots on your computer.
  4. If the AutoPlay prompt appears, dismiss the window.
  5. Get a command line window:
    • Windows: Click Start > All Programs > Accessories > Command Prompt - Right-click and click Run as administrator.
    • Mac OS: Click Finder > Go > Utilities > Terminal.
  6. Type adb devices
    Results:
    • Success - Under List of devices attached, the NOOK device serial number displays, which means that everything works and you can proceed to Install an App on a NOOK Device.
      > adb devices
      List of devices attached
      4242424242424242 device
      
      >
    • Unsuccessful - Under List of devices attached, no serial number displays and you should continue with the next section for additional troubleshooting information:
      > adb devices
      List of devices attached
      
      >

Troubleshooting

The goal of troubleshooting is for the adb devices command to list the serial number of your NOOK device.

  1. If not connected already, connect the NOOK device to your computer using the USB cable, power on the NOOK device, and open the desktop view.
  2. Re-update the ADB initialization file: android update adb
  3. Stop the ADB server: adb kill-server
  4. Restart the ADB server: adb start-server
  5. Eject the NOOK device, remove the USB cable, and reconnect the cable to your computer.
  6. See if NOOK device serial number appears: adb devices

If the NOOK device serial number appears after running these commands, proceed to the next section, Use Marmalade to Sideload an App.
If the NOOK device serial number still does not appear and you're using Windows, proceed to Appendix A: Get Windows to Recognize a NOOK Device. If you have a second NOOK device, try connecting that unit to your computer to see if the problem persists.

Back to Top

Use Marmalade to Sideload an App

To use Marmalade to sideload an app:

  1. Get a Marmalade license and software from madewithmarmalade.com. The license can be the Marmalade Evaluation license.
  2. Connect your NOOK device to your computer using the USB cable.
  3. Mac: Obtain access to Xcode and the Xorg server, which are free from Apple if you have Mac OS X Lion or Mountain Lion.
    Windows: Obtain access to Visual Studio. For a free version, download Microsoft Visual C++ Express.
  4. Create the MKB and ICF project files. If you're starting new with Marmalade, use their example project in the Marmalade install directory's examples/HelloWorld folder.
  5. Edit the MKB file, find the options section, and add the arm value for the NOOK ARM processor:
    options
    {
    
        strict
        arm
    }
  6. Build your app:
    1. Double-click the MKB file to launch your IDE (Visual Studio in Windows or Xcode in Mac). You can also start a build by right-clicking the MKB file or from the Marmalade LaunchPad utility.
    2. Mac: Click the Play button (circle with a right-facing triangle in the upper left of the Xcode window). You can ignore warnings that occur when Xcode launches.
      Windows: In Visual Studio, right-click the solution in the Solution Explorer and click Build Solution.
  7. Start the Deploy Tool.
    Mac: Locate the Marmalade install directory and click /Developer/Marmalade/6.0/Applications/DeployTool.app
    Windows: Click Start > All Programs > Marmalade > 6.0 > Tools > Deploy Tool.
    1. The Deploy Tool prompts for a Zest file (Marmalade project). Click the drop-down menu above the Open button and click Build_* directory *.py. Navigate to the Marmalade install directory, locate the deploy_config.py file and click Open.
    2. In the Deploy Tool, work through the respective menus by clicking Next and set:
      • At Stage: Select build:, click ARM GCC Debug or ARM GCC Release and click Next
      • At Stage: Configuration, in Select Configuration, click Default and click Next
      • In the Select Platform field, click Android and click Next
      • Set Package, Install, and Run and click Deploy All and click Next
      • The last screen shows the deployment progress. If deployment succeeds, an APK is created.
        If deployment fails, an error displays in the Progress field. Click the Log button for more information.
  8. Eject the NOOK device.
  9. On the NOOK device, press the NOOK button, and tap Apps.
  10. While holding the Volume Up button, tap the library symbol to view the Extras menu.
  11. You can then test your app from the Extras menu.

Back to Top

Handle the NOOK Button in Marmalade

The following sample loop that handles the "n" button on NOOK devices:

while (!s3eDeviceCheckQuitRequest() 
&& !(s3eKeyboardGetState(s3eKeyBack) & S3E_KEY_STATE_PRESSED)) 
{ 
// Fill background blue 
s3eSurfaceClear(0, 0, 255);

// Print a line of debug text to the screen at the top left (0,0) 
// Starting the text with the ` (backtick) char followed by "x" and a hex value, 
// determines the color of the text. 
s3eDebugPrint(120, 150, "`xffffffHello, World!", 0);

// Flip the surface buffer to screen 
s3eSurfaceShow();

// Update the keyboard 
s3eKeyboardUpdate(); 

// Sleep for 0ms to allow the OS to process events etc. 
s3eDeviceYield(0); 
}

Notes:

  • The program doesn't quit if you use S3E_KEY_STATE_DOWN. It also doesn't work if you don't have the s3eKeyboardUpdate() function in the right places for your loop. If the Back button is pressed and if the app is in fullscreen mode, your app has to yield to the OS to process the keyboard update. Hence, request the update, go to sleep, and let the OS handle the rest.
  • When the app is in fullscreen, the NOOK button is treated as Back. There is also a s3eKeyAbsBSK, which is not tied to the NOOK button. The AbsBSK is an "absolute back soft key", which is not seen when the application is in fullscreen mode.

Back to Top


Appendix A: Get Windows to Recognize a NOOK Device

This section handles differences in the setup for Windows.

Install Android Drivers (Windows Only)

This section gets the drivers for your computer to communicate with the NOOK device. (Mac OS doesn't require separate drivers to communicate with a NOOK device.)

To download and install Android drivers to a Windows computer:

  1. Unplug the USB cable from your NOOK device.
  2. Log on to the NOOK Developer site at http://www.nookdeveloper.com
  3. Click, or copy and paste this URL into your browser's address bar:
    https://nookdeveloper.zendesk.com/entries/22084221-windows-drivers-for-nook

    Note These drivers work for Windows 7, Windows Vista, and Windows XP.

    If you see You do not have access to this topic or 403: Access Forbidden, go to http://nookdeveloper.com and log in.
  4. Right click the usb_driver_r04-windows.zip file and click Save link as. Locate the folder to store the file and click Save.
  5. Unzip the driver file, which creates the usb_driver_r04-windows directory. Open this directory.
  6. Click Start, right-click Computer, and click Properties. Click Device Manager:
  7. Expand Other devices and look for NOOK Tablet or NOOKcolor. If a NOOK device is present and has a yellow symbol to the left of the name, right-click the device name and click Update Driver Software.
  8. If a NOOK device does not display under Other devices:
    1. Connect the USB cable to the NOOK device and to your computer.
    2. Close and reopen the Device Manager window.
  9. Click Browse my computer for driver software.
  10. Click Browse and locate the usb_driver_r04-windows directory where you unzipped the driver software in Step 4, and click OK.
  11. Click Next.
  12. Click Install this driver software anyway.

When done, a message prompt displays with Windows has successfully updated your driver software.

  1. Click Close.
  2. Unplug the NOOK device and plug it back into the USB port. Windows installs the drivers.
  3. When done, click Close.

Continue to Provision a NOOK Device.

Back to Top

Get Windows to see the NOOK Device

If the adb devices command did not display the serial number of the NOOK device and you're using a Windows computer, use the sections that follow to troubleshoot the issue.

Install Google USB Driver (Windows Only)

  1. Click Start > All Programs > Android SDK Tools
  2. Right-click SDK Manager and click Run as administrator.
  3. Under Extras, click Google USB Driver, and click Install 1 package.
  4. If the package appears with a question mark, click Accept, and click Install.
    When successful, the SDK Manager lists the package as Installed. If the SDK Manager runs, but does not install the package, ensure you used Run as administrator to start the SDK Manager.

Back to Top

Get Android Composite ADB Interface Driver (Windows Only)

This section describes how to get Windows to install additional drivers in the Device Manager. The goal is for Windows to install the Android Composite ADB Interface driver in the Android Phone category of Device Manager. Once the ACAI driver appears, you should be able to see the NOOK device in the Command Prompt using the adb devices command.

To get Windows to install the Android Composite ADB Interface driver:

  1. Click Start, right-click Computer, and click Properties. Click Device Manager.
  2. If Android Phone displays in the Device Manager, skip to Step 12.
  3. Click Action > Add legacy hardware.
  4. In the Add Hardware wizard, click Next.
  5. Click Install the hardware I manually select from a list (Advanced) and click Next.
  6. In the Common hardware types list, leave the setting at Show All Devices and click Next.
  7. Click Have Disk.
  8. Click Browse. Browse to:
    C:\Program Files (x86)\Android\android-sdk\extras\google\usb_driver\android_winusb.inf
    After locating the android_winusb.inf file, click OK.
  9. Click Open.
  10. Click OK in the Install From Disk window.
  11. Complete the installation by clicking Next, Next, Install, and Finish.
  12. After the installation completes, Android Phone is now visible in Device Manager. Expand Android Phone to show Android ADB Interface.
    Important If you see the Android Composite ADB Interface driver, retest the adb devices command in the Command Prompt. If the NOOK device serial number appears in the adb devices command, your installation is successful and you can return to the previous section, Use Marmalade to Sideload an App. If the NOOK device still does not appear in the adb devices command, continue.
  13. If the Android ADB Interface has a yellow warning icon beside the name, double-click Android ADB Interface to see the warning. The typical status is "This device cannot start. (Code 10)”. This is normal and you can ignore it. Click OK to dismiss.

Continue to the next section, Uninstall NOOK USB Drivers.

Back to Top

Uninstall Default USB Drivers (Windows Only)

In this section, you uninstall the default USB driver that Windows automatically installed for the attached NOOK device. The purpose is to get the Android Composite ADB Interface driver to appear in the Android Phone category. If you already have this driver, you can skip this section.

Locate USB Controllers

In the Device Manager, expand Universal Serial Bus controllers. The driver is labeled USB Mass Storage Device.

More Than One USB Mass Storage Device

If there is more than one USB Mass Storage Device, either delete all of them and Windows should re-install any later, or find the correct one for the NOOK device as follows.

To find the Mass Storage driver to keep:

  1. Open a text file with Notepad or another editor.
  2. Unplug the NOOK device's USB connection from your computer.
  3. Double-click each USB Mass Device items that remain, click the General tab, select and copy the Location value, paste the string into the text file, and click OK.
    For example, on one system it was Port_#0001.Hub_#0004. Each location is different and may be a long list of numbers. These are the drivers to leave alone.
  4. Plug the USB cable for the NOOK device back into your computer and locate any new USB Mass Storage Device items. You may need to compare your text file with the Location values to the new items to determine which is new.
  5. For the new USB Mass Storage Device items, right-click and click Uninstall.
  6. Unplug and re-plug the USB cable between the NOOK device and your computer. Windows re-installs a Mass Device driver, which you can now ignore. The ADB should now also install another driver, the Android Composite ADB Interface driver in the Android Phone category. Once this driver appears, return to the Command Prompt and retest the adb devices command. If the NOOK device's serial number appears in the adb devices command, you're now done.

Note Repeat this process for each NOOK device that doesn't appear in the adb devices command. Once done, Windows seems to keep it all straight as you plug and unplug devices. Also note that you can attach multiple NOOK devices to Windows at the same time once you have gone through this process for each NOOK device, this includes a mix of NOOK devices or multiples of the same NOOK device type.

Return to the previous section, Use Marmalade to Sideload an App.

Back to Top

 
Topic is closed for comments