def installOneApp(dm, devRoot, app_file_local_path, errorFile, logcat=True):

    source = app_file_local_path
    filename = os.path.basename(source)
    target = os.path.join(devRoot, filename)

    log.info("Installing %s" % target)
    if dm.pushFile(source, target):
        status = dm.installApp(target)
        if status is None:
            log.info('-' * 42)
            log.info('installApp() done - gathering debug info')
            dm.getInfo('process')
            dm.getInfo('memory')
            dm.getInfo('uptime')
            if logcat:
                try:
                    print dm._runCmds([{'cmd': 'exec su -c "logcat -d -v time *:W"'}])
                except devicemanager.DMError, e:
                    setFlag(errorFile, "Remote Device Error: Exception hit while trying to run logcat: %s" % str(e))
                    return 1
        else:
            setFlag(errorFile,
                    "Remote Device Error: updateApp() call failed - exiting")
            return 1

def checkSDCard(dm):
    """ Attempt to write a temp file to the SDCard

    We use this existing verify script as the source of the temp file

    Returns False on failure, True on Success
    """
    if not dmAlive(dm):
        return False

    try:
        if not dm.dirExists("/mnt/sdcard"):
            setFlag(errorFile, "Remote Device Error: Mount of sdcard does not seem to exist")
            return False
        if dm.fileExists("/mnt/sdcard/writetest"):
            log.info("INFO: /mnt/sdcard/writetest left over from previous run, cleaning")
            dm.removeFile("/mnt/sdcard/writetest")
        log.info("INFO: attempting to create file /mnt/sdcard/writetest")
        if not dm.pushFile(os.path.join(os.path.abspath(os.path.dirname(__file__)), "verify.py"), "/mnt/sdcard/writetest"):
            setFlag(
                errorFile, "Remote Device Error: unable to write to sdcard")
            return False
        if not dm.fileExists("/mnt/sdcard/writetest"):
            setFlag(errorFile, "Remote Device Error: Written tempfile doesn't exist on inspection")
            return False
        if not dm.removeFile("/mnt/sdcard/writetest"):
            setFlag(errorFile, "Remote Device Error: Unable to cleanup from written tempfile")
            return False
    except Exception, e:
        setFlag(errorFile, "Remote Device Error: Unknown error while testing ability to write to "
                           "sdcard, see following exception: %s" % e)
        return False

def setWatcherINI(dm):
    """ If necessary Installs the (correct) watcher.ini for our infra

    Returns False on failure, True on Success
    """
    import hashlib
    realLoc = "/data/data/com.mozilla.watcher/files/watcher.ini"
    currentHash = hashlib.md5(watcherINI).hexdigest()

    def watcherDataCurrent():
        remoteFileHash = dm._getRemoteHash(realLoc)
        if currentHash != remoteFileHash:
            return False
        else:
            return True

    if not dmAlive(dm):
        return False

    try:
        if watcherDataCurrent():
            return True
    except:
        setFlag(errorFile, "Unable to identify if watcher.ini is current")
        return False

    tmpname = '/mnt/sdcard/watcher.ini'
    try:
        dm._runCmds([{'cmd': 'push %s %s' % (tmpname, len(
            watcherINI)), 'data': watcherINI}])
    except devicemanager.AgentError, err:
        log.info("Error while pushing watcher.ini: %s" % err)
        setFlag(errorFile, "Unable to properly upload the watcher.ini")
        return False

def installOneApp(dm, devRoot, app_file_local_path):

    source = app_file_local_path
    filename = os.path.basename(source)
    target = os.path.join(devRoot, filename)

    global proxyFile, errorFile

    print "Installing %s" % target
    if dm.pushFile(source, target):
        status = dm.installApp(target)
        if status is None:
            print "-" * 42
            print "installApp() done - gathering debug info"
            dm.getInfo("process")
            dm.getInfo("memory")
            dm.getInfo("uptime")
            try:
                print dm.sendCMD(['exec su -c "logcat -d -v time *:W"'])
            except devicemanager.DMError, e:
                print "Exception hit while trying to run logcat: %s" % str(e)
                setFlag(errorFile, "Remote Device Error: can't run logcat")
                sys.exit(1)
        else:
            clearFlag(proxyFile)
            setFlag(errorFile, "Remote Device Error: updateApp() call failed - exiting")
            sys.exit(1)

def cleanupFoopy(device=None):
    errcode = checkStalled(device)
    if errcode == 2:
        log.error("processes from previous run were detected and cleaned up")
    elif errcode == 3:
        pidDir = os.path.join('/builds/', device)
        errorFile = os.path.join(pidDir, 'error.flg')
        setFlag(errorFile,
                "Remote Device Error: process from previous test run present")
        return RETCODE_KILLSTALLED
    return RETCODE_SUCCESS

def dmAlive(dm):
    """ Check that a devicemanager connection is still active

    Returns False on failure, True on Success
    """
    try:
        # We want to be paranoid for the types of exceptions we might get
        if dm.getCurrentTime():
            return True
    except:
        pass  # the actual exception holds no additional value here
    setFlag(errorFile,
            "Automation Error: Device manager lost connection to device")
    return False

def cleanupFoopy(device):
    """ Do cleanup actions necessary to ensure foopy in a good state

    Returns False on failure, True on Success
    """
    import cleanup
    retval = cleanup.cleanupFoopy(device=device)
    if retval == cleanup.RETCODE_SUCCESS:
        # All is good
        return True
    # else:
    setFlag(errorFile,
            "Automation Error: Unable to properly cleanup foopy processes")
    return False

def checkVersion(dm, flag=False):
    """ Verify SUTAgent Version

    Returns False on failure, True on Success
    """
    if not dmAlive(dm):
        return False

    ver = updateSUT.version(dm)
    if not updateSUT.isVersionCorrect(ver=ver):
        if flag:
            setFlag(errorFile, "Remote Device Error: Unexpected ver on device, got '%s' expected '%s'" %
                    (ver, "SUTAgentAndroid Version %s" % updateSUT.target_version))
        return False
    log.info(
        "INFO: Got expected SUTAgent version '%s'" % updateSUT.target_version)
    return True

def reboot(dm):
    cwd = os.getcwd()
    deviceName = os.path.basename(cwd)
    errorFile = os.path.join(cwd, '..', 'error.flg')
    proxyIP = getOurIP()
    proxyPort = calculatePort()

    if 'panda' not in deviceName:
        # Attempt to set devicename via env variable 'SUT_NAME'
        sname = os.getenv('SUT_NAME')
        if sname.strip():
            deviceName = sname.strip()
        else:
            log.info("Unable to find a proper devicename, will attempt to "
                     "reboot device")

    if dm is not None:
        try:
            dm.getInfo('process')
            log.info(dm._runCmds(
                [{'cmd': 'exec su -c "logcat -d -v time *:W"'}], timeout=10))
        except:
            log.info("Failure trying to run logcat on device")
    else:
        log.info("We were unable to connect to device %s, skipping logcat" %
                 deviceName)

    try:
        log.info('forcing device %s reboot' % deviceName)
        status = powermanagement.soft_reboot_and_verify(
            dm=dm,
            device=deviceName,
            ipAddr=proxyIP,
            port=proxyPort,
            silent=True
        )
        log.info(status)
    except:
        log.info("Failure while rebooting device")
        setFlag(errorFile,
                "Remote Device Error: Device failed to recover after reboot",
                True)
        return 1

    sys.stdout.flush()
    return 0

def cleanupDevice(device=None, dm=None):
    assert ((device is not None) or (dm is not None))  # Require one to be set

    if not device:
        device = os.environ['SUT_NAME']
    pidDir = os.path.join('/builds/', device)
    errorFile = os.path.join(pidDir, 'error.flg')
    reboot_needed = False

    processNames = ['org.mozilla.fennec_aurora',
                    'org.mozilla.fennec_unofficial',
                    'org.mozilla.fennec',
                    'org.mozilla.firefox_beta',
                    'org.mozilla.firefox',
                    'org.mozilla.roboexample.test',
                    ]

    if dm is None:
        log.info("Connecting to: " + device)
        dm = devicemanager.DeviceManagerSUT(device)
        dm.debug = 5

    packages = dm._runCmds([{'cmd': 'exec pm list packages'}])
    for package in packages.split('\n'):
        if not package.strip().startswith("package:"):
            continue  # unknown entry
        package_basename = package.strip()[8:]
        for proc in processNames:
            if package_basename == "%s" % proc or \
                    package_basename.startswith("%s_" % proc):
                log.info("Uninstalling %s..." % package_basename)
                try:
                    if 'panda' in device:
                        dm.uninstallApp(package_basename)
                        reboot_needed = True
                    else:
                        dm.uninstallAppAndReboot(package_basename)
                        waitForDevice(dm)
                except devicemanager.DMError, err:
                    setFlag(errorFile,
                            "Remote Device Error: Unable to uninstall %s and reboot: %s" % (package_basename, err))
                    return RETCODE_ERROR
                finally:
                    break  # Don't try this proc again, since we already matched

def cleanupDevice(device, dm):
    """ Do cleanup actions necessary to ensure starting in a good state

    Returns False on failure, True on Success
    """
    if not dmAlive(dm):
        return False

    import cleanup
    try:
        retval = cleanup.cleanupDevice(device=device, dm=dm)
        if retval == cleanup.RETCODE_SUCCESS:
            # All is good
            return True
    except:
        setFlag(errorFile,
                "Remote Device Error: Unhandled exception in cleanupDevice")
    # Some sort of error happened above
    return False

def canPing(device):
    """ Check a device is reachable by ping

    Returns False on failure, True on Success
    """
    curRetry = 0
    log.info("INFO: attempting to ping device")
    while curRetry < MAX_RETRIES:
        ret, _ = pingDevice(device)
        if not ret:
            curRetry += 1
            if curRetry == MAX_RETRIES:
                setFlag(errorFile, "Automation Error: Unable to ping device after %s attempts" % MAX_RETRIES)
                return False
            else:
                log.info("INFO: Unable to ping device after %s try. Sleeping for 90s then retrying" % curRetry)
                time.sleep(90)
        else:
            break  # we're done here
    return True

def updateSUTVersion(dm):
    """ Update SUTAgent Version

    Returns False on failure, True on Success
    """
    if not dmAlive(dm):
        return False

    retcode = updateSUT.doUpdate(dm)
    if retcode == updateSUT.RETCODE_SUCCESS:
        return True
    elif retcode == updateSUT.RETCODE_APK_DL_FAILED:
        setFlag(errorFile, "Remote Device Error: UpdateSUT: Unable to download "
                "new APK for SUTAgent")
    elif retcode == updateSUT.RETCODE_REVERIFY_FAILED:
        setFlag(errorFile, "Remote Device Error: UpdateSUT: Unable to re-verify "
                "that the SUTAgent was updated")
    elif retcode == updateSUT.RETCODE_REVERIFY_WRONG:
        # We will benefit from the SUT Ver being displayed on our dashboard
        if checkVersion(dm, flag=True):
            # we NOW verified correct SUT Ver, Huh?
            setFlag(errorFile, " Unexpected State: UpdateSUT found incorrect SUTAgent Version after "
                    "updating, but we seem to be correct now.")
    # If we get here we failed to update properly
    return False

def checkAndFixScreen(dm, device):
    """ Verify the screen is set as we expect

    If the screen is incorrectly set, this function attempts to fix it,
    which ends up requiring a reboot of the device.

    Returns False if screen is wrong, True if correct
    """
    if not dmAlive(dm):
        return False

    # Verify we have the expected screen resolution
    info = dm.getInfo("screen")
    if not info["screen"][0] == EXPECTED_DEVICE_SCREEN:
        setFlag(errorFile, "Remote Device Error: Unexpected Screen on device, got '%s' expected '%s'" %
               (info["screen"][0], EXPECTED_DEVICE_SCREEN))
        if not dm.adjustResolution(**EXPECTED_DEVICE_SCREEN_ARGS):
            setFlag(errorFile, "Command to update resolution returned failure")
        else:
            soft_reboot(dm=dm, device=device)
                        # Reboot sooner than cp would trigger a hard Reset
        return False
    log.info("INFO: Got expected screen size '%s'" % EXPECTED_DEVICE_SCREEN)
    return True

def canTelnet(device):
    """ Checks if we can establish a Telnet session (via devicemanager)

    Sets global `dm`
    Returns False on failure, True on Success
    """
    global dm
    curRetry = 0
    sleepDuration = 0
    while curRetry < MAX_RETRIES:
        try:
            dm = connect(device, sleepDuration)
        except:
            curRetry += 1
            if curRetry == MAX_RETRIES:
                setFlag(errorFile, "Automation Error: Unable to connect to device after %s attempts" % MAX_RETRIES)
                return False
            else:
                log.info("INFO: Unable to connect to device after %s try" %
                         curRetry)
                sleepDuration = 90
        else:
            break  # We're done here
    return True

    tmpname = '/mnt/sdcard/watcher.ini'
    try:
        dm._runCmds([{'cmd': 'push %s %s' % (tmpname, len(
            watcherINI)), 'data': watcherINI}])
    except devicemanager.AgentError, err:
        log.info("Error while pushing watcher.ini: %s" % err)
        setFlag(errorFile, "Unable to properly upload the watcher.ini")
        return False

    try:
        dm._runCmds(
            [{'cmd': 'exec su -c "dd if=%s of=%s"' % (tmpname, realLoc)}])
    except devicemanager.AgentError, err:
        log.info("Error while moving watcher.ini to %s: %s" % (realLoc, err))
        setFlag(errorFile, "Unable to properly upload the watcher.ini")
        return False

    try:
        dm._runCmds([{'cmd': 'exec su -c "chmod 0777 %s"' % realLoc}])
    except devicemanager.AgentError, err:
        log.info("Error while setting permissions for %s: %s" % (realLoc, err))
        setFlag(errorFile, "Unable to properly upload the watcher.ini")
        return False

    try:
        if watcherDataCurrent():
            return True
    except:
        pass
    setFlag(errorFile, "Unable to verify the updated watcher.ini")

def one_time_setup(ip_addr, major_source):
    ''' One time setup of state

    ip_addr - of the device we want to install app at
    major_source - we've hacked this script to install
            may-also-be-needed tools, but the source we're asked to
            install has the meta data we need

    Side Effects:
        global, needed for error reporting:
            errorFile
    '''

    # set up the flag files, used throughout
    cwd = os.getcwd()
    global errorFile
    errorFile = os.path.join(cwd, '..', 'error.flg')
    deviceName = os.path.basename(cwd)

    proxyIP = getOurIP()
    proxyPort = calculatePort()

    workdir = os.path.dirname(major_source)
    inifile = os.path.join(workdir, 'fennec', 'application.ini')
    remoteappini = os.path.join(workdir, 'talos', 'remoteapp.ini')
    log.info('copying %s to %s' % (inifile, remoteappini))
    runCommand(['cp', inifile, remoteappini])

    log.info("connecting to: %s" % ip_addr)
    dm = devicemanager.DeviceManagerSUT(ip_addr)
# Moar data!
    dm.debug = 3

    devRoot = checkDeviceRoot(dm)

    if devRoot is None or devRoot == '/tests':
        setFlag(errorFile, "Remote Device Error: devRoot from devicemanager [%s] is not correct - exiting" % devRoot)
        return None, None

    try:
        log.info("%s, %s" % (proxyIP, proxyPort))
        getDeviceTimestamp(dm)
        setDeviceTimestamp(dm)
        getDeviceTimestamp(dm)
        dm.getInfo('process')
        dm.getInfo('memory')
        dm.getInfo('uptime')

        width, height = getResolution(dm)
        # adjust resolution down to allow fennec to install without memory
        # issues
        if (width == 1600 or height == 1200):
            dm.adjustResolution(1024, 768, 'crt')
            log.info('forcing device reboot')
            if not powermanagement.soft_reboot_and_verify(device=deviceName, dm=dm, ipAddr=proxyIP, port=proxyPort):
                return None, None

            width, height = getResolution(dm)
            if width != 1024 and height != 768:
                setFlag(errorFile, "Remote Device Error: Resolution change failed.  Should be %d/%d but is %d/%d" % (1024, 768, width, height))
                return None, None

    except devicemanager.AgentError, err:
        log.error("remoteDeviceError: while doing one time setup for installation: %s" % err)
        return None, None

if (len(sys.argv) <> 2):
  print "usage: reboot.py <ip address>"
  sys.exit(1)

cwd       = os.getcwd()
proxyFile = os.path.join(cwd, '..', 'proxy.flg')
errorFile = os.path.join(cwd, '..', 'error.flg')
proxyIP   = getOurIP()
proxyPort = calculatePort()

print "connecting to: %s" % sys.argv[1]
dm = devicemanager.DeviceManagerSUT(sys.argv[1])
dm.debug = 5

setFlag(proxyFile)
try:
    dm.getInfo('process')
    print dm.sendCMD(['exec su -c "logcat -d -v time *:W"'])

    print 'calling dm.reboot()'

    status = dm.reboot(ipAddr=proxyIP, port=proxyPort)
    print status
finally:
    try:
        waitForDevice(dm, waitTime=600)
    except SystemExit:
        clearFlag(proxyFile)
        setFlag(errorFile, "Remote Device Error: call for device reboot failed")
        sys.exit(1)

                            "Remote Device Error: Unable to uninstall %s and reboot: %s" % (package_basename, err))
                    return RETCODE_ERROR
                finally:
                    break  # Don't try this proc again, since we already matched

    if reboot_needed:
        if not powermanagement.soft_reboot_and_verify(device, dm):
            # NOTE: powermanagement.soft_reboot_and_verify will setFlag if needed
            return RETCODE_ERROR

    # Now Verify that they are all gone
    packages = dm._runCmds([{'cmd': 'exec pm list packages'}])
    for package in packages.split('\n'):
        for proc in processNames:
            if package == "package:%s" % proc:
                setFlag(errorFile, "Remote Device Error: Unable to properly uninstall %s" % proc)
                return RETCODE_ERROR

    devRoot = checkDeviceRoot(dm)

    if not str(devRoot).startswith("/mnt/sdcard"):
        setFlag(errorFile, "Remote Device Error: devRoot from devicemanager [%s] is not correct" % str(devRoot))
        return RETCODE_ERROR

    if dm.dirExists(devRoot):
        status = dm.removeDir(devRoot)
        log.info("removeDir() returned [%s]" % status)
        if status is None or not status:
            setFlag(errorFile, "Remote Device Error: call to removeDir() returned [%s]" % status)
            return RETCODE_ERROR
        if dm.dirExists(devRoot):

def one_time_setup(ip_addr, major_source):
    """ One time setup of state

    ip_addr - of the tegra we want to install app at
    major_source - we've hacked this script to install
            may-also-be-needed tools, but the source we're asked to
            install has the meta data we need

    Side Effects:
        We two globals, needed for error reporting:
            errorFile, proxyFile
    """

    # set up the flag files, used throughout
    cwd = os.getcwd()
    global proxyFile, errorFile
    proxyFile = os.path.join(cwd, "..", "proxy.flg")
    errorFile = os.path.join(cwd, "..", "error.flg")

    proxyIP = getOurIP()
    proxyPort = calculatePort()

    workdir = os.path.dirname(major_source)
    inifile = os.path.join(workdir, "fennec", "application.ini")
    remoteappini = os.path.join(workdir, "talos", "remoteapp.ini")
    print "copying %s to %s" % (inifile, remoteappini)
    runCommand(["cp", inifile, remoteappini])

    print "connecting to: %s" % ip_addr
    dm = devicemanager.DeviceManagerSUT(ip_addr)
    # Moar data!
    dm.debug = 3

    devRoot = checkDeviceRoot(dm)

    if devRoot is None or devRoot == "/tests":
        setFlag(errorFile, "Remote Device Error: devRoot from devicemanager [%s] is not correct - exiting" % devRoot)
        sys.exit(1)

    try:
        setFlag(proxyFile)
        print proxyIP, proxyPort
        getDeviceTimestamp(dm)
        setDeviceTimestamp(dm)
        getDeviceTimestamp(dm)
        dm.getInfo("process")
        dm.getInfo("memory")
        dm.getInfo("uptime")

        width, height = getResolution(dm)
        # adjust resolution down to allow fennec to install without memory issues
        if width >= 1050 or height >= 1050:
            dm.adjustResolution(1024, 768, "crt")
            print "calling reboot"
            dm.reboot(proxyIP, proxyPort)
            waitForDevice(dm)

            width, height = getResolution(dm)
            if width != 1024 and height != 768:
                clearFlag(proxyFile)
                setFlag(
                    errorFile,
                    "Remote Device Error: Resolution change failed.  Should be %d/%d but is %d/%d"
                    % (1024, 768, width, height),
                )
                sys.exit(1)

    finally:
        clearFlag(proxyFile)

    return dm, devRoot