Console - The API to use

Console

Console class is a wrapper around the protocol, can be used to discover, poweron and connect. Also stores various device status informations.

It can be either created manually or instantiated via DiscoveryResponse message. However, calling static method discover does all that for you automatically.

Example

Discovery and connecting:

import sys
from xbox.sg.console import Console
from xbox.sg.enum import ConnectionState

discovered = await Console.discover(timeout=1)
if len(discovered):
    console = discovered[0]
    await console.connect()
    if console.connection_state != ConnectionState.Connected:
        print("Connection failed")
        sys.exit(1)
    await console.wait(1)
else:
    print("No consoles discovered")
    sys.exit(1)

... do stuff ...
class xbox.sg.console.Console(address: str, name: str, uuid: uuid.UUID, liveid: str, flags: xbox.sg.enum.PrimaryDeviceFlag = <PrimaryDeviceFlag.Null: 0>, last_error: int = 0, public_key: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey = None)

Bases: object

__init__(address: str, name: str, uuid: uuid.UUID, liveid: str, flags: xbox.sg.enum.PrimaryDeviceFlag = <PrimaryDeviceFlag.Null: 0>, last_error: int = 0, public_key: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey = None)

Initialize an instance of Console

Parameters

  • address – IP address of console.

  • flags – Primary device flags

  • name – Name of console.

  • uuid – UUID of console.

  • liveid – Live ID of console.

  • public_key – Console’s Public Key.

async static wait(seconds: int) → None

Wrapper around asyncio.sleep

Parameters

seconds – Seconds to wait.

Returns: None

async _ensure_protocol_started() → None

Regular protocol instance, setup with crypto and destination address. Targeted at communication with a specific console.

Returns

None

async classmethod _ensure_global_protocol_started() → None

Global protocol instance, used for network wide discovery and poweron.

classmethod from_message(address: str, msg: xbox.sg.utils.struct.XStruct)

Initialize the class with a DiscoveryResponse.

Parameters

  • address – IP address of the console

  • msg – Discovery Response struct

Returns: Console instance

classmethod from_dict(d: dict)
to_dict() → dict
add_manager(manager: Type[xbox.sg.manager.Manager], *args, **kwargs)

Add a manager to the console instance.

This will inherit all public methods of the manager class.

Parameters

  • manager – Manager to add

  • *args – Arguments

  • **kwargs – KwArguments

Returns

None

async classmethod discover(*args, **kwargs) → List

Discover consoles on the network.

Parameters

  • *args –

  • **kwargs –

Returns

List of discovered consoles.

Return type

list

classmethod discovered() → List

Get list of already discovered consoles.

Returns

List of discovered consoles.

Return type

list

async classmethod power_on(liveid: str, addr: Optional[str] = None, tries=2) → None

Power On console with given Live ID.

Optionally the IP address of the console can be supplied, this is useful if the console is stubborn and does not react to broadcast / multicast packets (due to routing issues).

Parameters

  • liveid (str) – Live ID of console.

  • addr (str) – IP address of console.

  • tries (int) – Poweron attempts, default: 2.

Returns: None

async send_message(msg: xbox.sg.utils.struct.XStruct, channel: xbox.sg.enum.ServiceChannel = <ServiceChannel.Core: 0>, addr: Optional[str] = None, blocking: bool = True, timeout: int = 5, retries: int = 3) → Optional[xbox.sg.utils.struct.XStruct]

Send message to console.

Parameters

  • msg – Unassembled message to send

  • channel – Channel to send the message on, Enum member of ServiceChannel

  • addr – IP address of target console

  • blocking – If set and msg is Message-packet, wait for ack

  • timeout – Seconds to wait for ack, only useful if blocking is True

  • retries – Max retry count.

Returns: None

async json(data: str, channel: xbox.sg.enum.ServiceChannel) → None

Send json message

Parameters

  • data – JSON dict

  • channel – Channel to send the message to

Returns: None

async connect(userhash: Optional[str] = None, xsts_token: Optional[str] = None) → xbox.sg.enum.ConnectionState

Connect to the console

If the connection fails, error will be stored in self.connection_state

Raises

ConnectionException – If no authentication data is supplied and console disallows anonymous connection.

Returns: Connection state

async launch_title(uri: str, location: xbox.sg.enum.ActiveTitleLocation = <ActiveTitleLocation.Full: 0>) → xbox.sg.enum.AckStatus

Launch a title by URI

Parameters

  • uri – Launch uri

  • location – Target title location

Returns: Ack status

async game_dvr_record(start_delta: int, end_delta: int) → xbox.sg.enum.AckStatus

Start Game DVR recording

Parameters

  • start_delta – Start time

  • end_delta – End time

Returns: Ack status

async disconnect() → None

Disconnect from console.

This will reset connection-, pairing-state, ActiveSurface and ConsoleStatus.

Returns: None

async power_off() → None

Power off the console.

No need to disconnect after.

Returns: None

_handle_message(msg: xbox.sg.utils.struct.XStruct, channel: xbox.sg.enum.ServiceChannel) → None

Internal handler for console specific messages aka. PairedIdentityStateChange, ConsoleStatus and ActiveSurfaceChange.

Parameters

  • msg – Message data

  • channel – Service channel

Returns

None

_handle_json(msg: xbox.sg.utils.struct.XStruct, channel: xbox.sg.enum.ServiceChannel) → None

Internal handler for JSON messages

Parameters

  • msg – JSON message instance

  • channel – Service channel originating from

Returns: None

_handle_timeout() → None

Internal handler for console connection timeout.

Returns: None

async _reset_state() → None

Internal handler to reset the inital state of the console instance.

Returns: None

property public_key

Console’s public key.

Returns: Foreign public key

property device_status

Current availability status

Returns

DeviceStatus

property connection_state

Current connection state

Returns: Connection state

property pairing_state

Current pairing state

Returns

PairedIdentityState

property console_status

Console status aka. kernel version, active titles etc.

Returns

XStruct

property active_surface

Currently active surface

Returns

XStruct

property available

Check whether console is available aka. discoverable

Returns: True if console is available, False otherwise

property paired

Check whether client is paired to console

Returns: True if console is paired, False otherwise

property connected

Check whether client is successfully connected to console

Returns: True if connected, False otherwise

property authenticated_users_allowed

Check whether authenticated users are allowed to connect

Returns: True if authenticated users are allowed, False otherwise

property console_users_allowed

Check whether console users are allowed to connect

Returns: True if console users are allowed, False otherwise

property anonymous_connection_allowed

Check whether anonymous connection is allowed

Returns: True if anonymous connection is allowed, False otherwise

property is_certificate_pending

Check whether certificate is pending

Returns: True if certificate is pending, False otherwise