aio_androidtv.basetv module¶

Communicate with an Android TV or Amazon Fire TV device via ADB over a network.

ADB Debugging must be enabled.

class aio_androidtv.basetv.BaseTV(host, port=5555, adbkey='', state_detection_rules=None)[source]¶

Bases: object

Base class for representing an Android TV / Fire TV device.

The state_detection_rules parameter is of the format:

state_detection_rules = {'com.amazon.tv.launcher': ['idle'],
                         'com.netflix.ninja': ['media_session_state'],
                         'com.ellation.vrv': ['audio_state'],
                         'com.hulu.plus': [{'playing': {'wake_lock_size' : 4}},
                                           {'paused': {'wake_lock_size': 2}}],
                         'com.plexapp.android': [{'paused': {'media_session_state': 3, 'wake_lock_size': 1}},
                                                 {'playing': {'media_session_state': 3}},
                                                 'idle']}

The keys are app IDs, and the values are lists of rules that are evaluated in order.

VALID_STATES

VALID_STATES = ('idle', 'off', 'playing', 'paused', 'standby')

Valid rules:

'idle', 'playing', 'paused', 'standby', or 'off' = always report the specified state when this app is open
'media_session_state' = try to use the media_session_state() property to determine the state
'audio_state' = try to use the audio_state() property to determine the state
{'<VALID_STATE>': {'<PROPERTY1>': VALUE1, '<PROPERTY2>': VALUE2, ...}} = check if each of the properties is equal to the specified value, and if so return the state
- The valid properties are 'media_session_state', 'audio_state', and 'wake_lock_size'

Parameters

host (str) – The address of the device; may be an IP address or a host name
port (int) – The device port to which we are connecting (default is 5555)
adbkey (str) – The path to the adbkey file for ADB authentication
state_detection_rules (dict, None) – A dictionary of rules for determining the state (see above)

static _audio_output_device(stream_music)[source]¶

Get the current audio playback device from the STREAM_MUSIC block from adb shell dumpsys audio.

Parameters: stream_music (str, None) – The STREAM_MUSIC block from adb shell dumpsys audio
Returns: The current audio playback device, or None if it could not be determined
Return type: str, None

static _audio_state(audio_state_response)[source]¶

Parse the audio_state() property from the output of the command aio_androidtv.constants.CMD_AUDIO_STATE.

Parameters: audio_state_response (str, None) – The output of the command aio_androidtv.constants.CMD_AUDIO_STATE
Returns: The audio state, or None if it could not be determined
Return type: str, None

static _conditions_are_true(conditions, media_session_state=None, wake_lock_size=None, audio_state=None)[source]¶

Check whether the conditions in conditions are true.

Parameters

conditions (dict) – A dictionary of conditions to be checked (see the state_detection_rules parameter in BaseTV)
media_session_state (int, None) – The media_session_state() property
wake_lock_size (int, None) – The wake_lock_size() property
audio_state (str, None) – The audio_state() property

Returns

Whether or not all the conditions in conditions are true

Return type

bool

static _current_app(current_app_response)[source]¶

Get the current app from the output of the command aio_androidtv.constants.CMD_CURRENT_APP.

Parameters: current_app_response (str, None) – The output from the ADB command aio_androidtv.constants.CMD_CURRENT_APP
Returns: The current app, or None if it could not be determined
Return type: str, None

static _current_app_media_session_state(media_session_state_response)[source]¶

Get the current app and the media session state properties from the output of aio_androidtv.constants.CMD_MEDIA_SESSION_STATE_FULL.

Parameters

media_session_state_response (str, None) – The output of aio_androidtv.constants.CMD_MEDIA_SESSION_STATE_FULL

Returns

current_app (str, None) – The current app, or None if it could not be determined
media_session_state (int, None) – The state from the output of the ADB shell command, or None if it could not be determined

_custom_state_detection(current_app=None, media_session_state=None, wake_lock_size=None, audio_state=None)[source]¶

Use the rules in self._state_detection_rules to determine the state.

Parameters

current_app (str, None) – The current_app() property
media_session_state (int, None) – The media_session_state() property
wake_lock_size (int, None) – The wake_lock_size() property
audio_state (str, None) – The audio_state() property

Returns

The state, if it could be determined using the rules in self._state_detection_rules; otherwise, None

Return type

str, None

async _get_stream_music(stream_music_raw=None)[source]¶

Get the STREAM_MUSIC block from the output of the command aio_androidtv.constants.CMD_STREAM_MUSIC.

Parameters: stream_music_raw (str, None) – The output of the command aio_androidtv.constants.CMD_STREAM_MUSIC
Returns: The STREAM_MUSIC block from the output of aio_androidtv.constants.CMD_STREAM_MUSIC, or None if it could not be determined
Return type: str, None

static _is_volume_muted(stream_music)[source]¶

Determine whether or not the volume is muted from the STREAM_MUSIC block from adb shell dumpsys audio.

Parameters: stream_music (str, None) – The STREAM_MUSIC block from adb shell dumpsys audio
Returns: Whether or not the volume is muted, or None if it could not be determined
Return type: bool, None

async _key(key)[source]¶

Send a key event to device.

Parameters: key (str, int) – The Key constant

static _media_session_state(media_session_state_response, current_app)[source]¶

Get the state from the output of aio_androidtv.constants.CMD_MEDIA_SESSION_STATE.

Parameters

media_session_state_response (str, None) – The output of aio_androidtv.constants.CMD_MEDIA_SESSION_STATE
current_app (str, None) – The current app, or None if it could not be determined

Returns

The state from the output of the ADB shell command, or None if it could not be determined

Return type

int, None

static _parse_getevent_line(line)[source]¶

Parse a line of the output received in learn_sendevent.

Parameters: line (str) – A line of output from learn_sendevent
Returns: The properly formatted sendevent command
Return type: str

static _running_apps(running_apps_response)[source]¶

Get the running apps from the output of aio_androidtv.constants.CMD_RUNNING_APPS.

Parameters: running_apps_response (str, None) – The output of aio_androidtv.constants.CMD_RUNNING_APPS
Returns: A list of the running apps, or None if it could not be determined
Return type: list, None

async _send_intent(pkg, intent, count=1)[source]¶

Send an intent to the device.

Parameters

pkg (str) – The command that will be sent is monkey -p <pkg> -c <intent> <count>; echo $?
intent (str) – The command that will be sent is monkey -p <pkg> -c <intent> <count>; echo $?
count (int, str) – The command that will be sent is monkey -p <pkg> -c <intent> <count>; echo $?

Returns

A dictionary with keys 'output' and 'retcode', if they could be determined; otherwise, an empty dictionary

Return type

dict

_volume(stream_music, audio_output_device)[source]¶

Get the absolute volume level from the STREAM_MUSIC block from adb shell dumpsys audio.

Parameters

stream_music (str, None) – The STREAM_MUSIC block from adb shell dumpsys audio
audio_output_device (str, None) – The current audio playback device

Returns

The absolute volume level, or None if it could not be determined

Return type

int, None

_volume_level(volume)[source]¶

Get the relative volume level from the absolute volume level.

Parameters: volume (int, None) – The absolute volume level
Returns: The volume level (between 0 and 1), or None if it could not be determined
Return type: float, None

static _wake_lock_size(wake_lock_size_response)[source]¶

Get the size of the current wake lock from the output of aio_androidtv.constants.CMD_WAKE_LOCK_SIZE.

Parameters: wake_lock_size_response (str, None) – The output of aio_androidtv.constants.CMD_WAKE_LOCK_SIZE
Returns: The size of the current wake lock, or None if it could not be determined
Return type: int, None

async adb_close()[source]¶: Close the ADB connection.

async adb_connect(always_log_errors=True, auth_timeout_s=0.1)[source]¶

Connect to an Android TV / Fire TV device.

Parameters

always_log_errors (bool) – If True, errors will always be logged; otherwise, errors will only be logged on the first failed reconnect attempt
auth_timeout_s (float) – Authentication timeout (in seconds)

Returns

Whether or not the connection was successfully established and the device is available

Return type

bool

async adb_pull(local_path, device_path)[source]¶

Pull a file from the device.

This calls aio_androidtv.adb_manager.ADBPython.pull().

Parameters

local_path (str) – The path where the file will be saved
device_path (str) – The file on the device that will be pulled

async adb_push(local_path, device_path)[source]¶

Push a file to the device.

This calls aio_androidtv.adb_manager.ADBPython.push().

Parameters

local_path (str) – The file that will be pushed to the device
device_path (str) – The path where the file will be saved on the device

async adb_screencap()[source]¶

Take a screencap.

This calls aio_androidtv.adb_manager.ADBPython.screencap().

Returns: The screencap as a binary .png image
Return type: bytes

async adb_shell(cmd)[source]¶

Send an ADB command.

This calls aio_androidtv.adb_manager.ADBPython.shell().

Parameters: cmd (str) – The ADB command to be sent
Returns: The response from the device, if there is a response
Return type: str, None

async audio_output_device()[source]¶

Get the current audio playback device.

Returns: The current audio playback device, or None if it could not be determined
Return type: str, None

async audio_state()[source]¶

Check if audio is playing, paused, or idle.

Returns: The audio state, as determined from the ADB shell command aio_androidtv.constants.CMD_AUDIO_STATE, or None if it could not be determined
Return type: str, None

property available¶

Whether the ADB connection is intact.

Returns: Whether or not the ADB connection is intact
Return type: bool

async awake()[source]¶

Check if the device is awake (screensaver is not running).

Returns: Whether or not the device is awake (screensaver is not running)
Return type: bool

async back()[source]¶: Send back action.

async current_app()[source]¶

Return the current app.

Returns: The ID of the current app, or None if it could not be determined
Return type: str, None

async down()[source]¶: Send down action.

async enter()[source]¶: Send enter action.

async get_device_properties()[source]¶

Return a dictionary of device properties.

Returns: props – A dictionary with keys 'wifimac', 'ethmac', 'serialno', 'manufacturer', 'model', and 'sw_version'
Return type: dict

async home()[source]¶: Send home action.

async is_volume_muted()[source]¶

Whether or not the volume is muted.

Returns: Whether or not the volume is muted, or None if it could not be determined
Return type: bool, None

async key_0()[source]¶: Send 0 keypress.

async key_1()[source]¶: Send 1 keypress.

async key_2()[source]¶: Send 2 keypress.

async key_3()[source]¶: Send 3 keypress.

async key_4()[source]¶: Send 4 keypress.

async key_5()[source]¶: Send 5 keypress.

async key_6()[source]¶: Send 6 keypress.

async key_7()[source]¶: Send 7 keypress.

async key_8()[source]¶: Send 8 keypress.

async key_9()[source]¶: Send 9 keypress.

async key_a()[source]¶: Send a keypress.

async key_b()[source]¶: Send b keypress.

async key_c()[source]¶: Send c keypress.

async key_d()[source]¶: Send d keypress.

async key_e()[source]¶: Send e keypress.

async key_f()[source]¶: Send f keypress.

async key_g()[source]¶: Send g keypress.

async key_h()[source]¶: Send h keypress.

async key_i()[source]¶: Send i keypress.

async key_j()[source]¶: Send j keypress.

async key_k()[source]¶: Send k keypress.

async key_l()[source]¶: Send l keypress.

async key_m()[source]¶: Send m keypress.

async key_n()[source]¶: Send n keypress.

async key_o()[source]¶: Send o keypress.

async key_p()[source]¶: Send p keypress.

async key_q()[source]¶: Send q keypress.

async key_r()[source]¶: Send r keypress.

async key_s()[source]¶: Send s keypress.

async key_t()[source]¶: Send t keypress.

async key_u()[source]¶: Send u keypress.

async key_v()[source]¶: Send v keypress.

async key_w()[source]¶: Send w keypress.

async key_x()[source]¶: Send x keypress.

async key_y()[source]¶: Send y keypress.

async key_z()[source]¶: Send z keypress.

async launch_app(app)[source]¶

Launch an app.

Parameters: app (str) – The ID of the app that will be launched

async learn_sendevent(timeout_s=8)[source]¶

Capture an event (e.g., a button press) via getevent and convert it into sendevent commands.

For more info, see:

Parameters: timeout_s (int) – The timeout in seconds to wait for events
Returns: The events converted to sendevent commands
Return type: str

async left()[source]¶: Send left action.

async media_next_track()[source]¶: Send media next action (results in fast-forward).

async media_pause()[source]¶: Send media pause action.

async media_play()[source]¶: Send media play action.

async media_play_pause()[source]¶: Send media play/pause action.

async media_previous_track()[source]¶: Send media previous action (results in rewind).

async media_session_state()[source]¶

Get the state from the output of dumpsys media_session.

Returns: The state from the output of the ADB shell command dumpsys media_session, or None if it could not be determined
Return type: int, None

async media_stop()[source]¶: Send media stop action.

async menu()[source]¶: Send menu action.

async mute_volume()[source]¶: Mute the volume.

async power()[source]¶: Send power action.

async right()[source]¶: Send right action.

async screen_on()[source]¶

Check if the screen is on.

Returns: Whether or not the device is on
Return type: bool

async set_volume_level(volume_level)[source]¶

Set the volume to the desired level.

Parameters: volume_level (float) – The new volume level (between 0 and 1)
Returns: The new volume level (between 0 and 1), or None if self.max_volume could not be determined
Return type: float, None

async sleep()[source]¶: Send sleep action.

async space()[source]¶: Send space keypress.

async start_intent(uri)[source]¶

Start an intent on the device.

Parameters: uri (str) – The intent that will be sent is am start -a android.intent.action.VIEW -d <uri>

async stop_app(app)[source]¶

Stop an app.

Parameters: app (str) – The ID of the app that will be stopped
Returns: The output of the am force-stop ADB shell command, or None if the device is unavailable
Return type: str, None

async up()[source]¶: Send up action.

async volume()[source]¶

Get the absolute volume level.

Returns: The absolute volume level, or None if it could not be determined
Return type: int, None

async volume_down(current_volume_level=None)[source]¶

Send volume down action.

Parameters: current_volume_level (float, None) – The current volume level (between 0 and 1); if it is not provided, it will be determined
Returns: The new volume level (between 0 and 1), or None if self.max_volume could not be determined
Return type: float, None

async volume_level()[source]¶

Get the relative volume level.

Returns: The volume level (between 0 and 1), or None if it could not be determined
Return type: float, None

async volume_up(current_volume_level=None)[source]¶

Send volume up action.

Parameters: current_volume_level (float, None) – The current volume level (between 0 and 1); if it is not provided, it will be determined
Returns: The new volume level (between 0 and 1), or None if self.max_volume could not be determined
Return type: float, None

async wake_lock_size()[source]¶

Get the size of the current wake lock.

Returns: The size of the current wake lock, or None if it could not be determined
Return type: int, None

aio_androidtv.basetv.state_detection_rules_validator(rules, exc=<class 'KeyError'>)[source]¶

Validate the rules (i.e., the state_detection_rules value) for a given app ID (i.e., a key in state_detection_rules).

For each rule in rules, this function checks that:

rule is a string or a dictionary
If rule is a string:
- Check that rule is in VALID_STATES or VALID_STATE_PROPERTIES
If rule is a dictionary:
- Check that each key is in VALID_STATES
- Check that each value is a dictionary
  Check that each key is in VALID_PROPERTIES
  
  Check that each value is of the right type, according to VALID_PROPERTIES_TYPES

See BaseTV for more info about the state_detection_rules parameter.

Parameters

rules (list) – A list of the rules that will be used to determine the state
exc (Exception) – The exception that will be raised if a rule is invalid

Returns

rules – The provided list of rules

Return type

list