xbox-smartglass-core 1.2.0

A library to interact with the Xbox One gaming console via the SmartGlass protocol.

Xbox-Smartglass-Core

This library provides the core foundation for the smartglass protocol that is used with the Xbox One Gaming console

For in-depth information, check out the documentation: (https://openxbox.org/smartglass-documentation)

NOTE: Since 29.02.2020 the following modules are integrated into core: stump, auxiliary, rest-server

NOTE: Nano module is still offered seperately

Features

• Power on / off the console

• Get system info (running App/Game/Title, dashboard version)

• Media player control (seeing content id, content app, playback actions etc.)

• Stump protocol (Live-TV Streaming / IR control)

• Title / Auxiliary stream protocol (f.e. Fallout 4 companion app)

• Trigger GameDVR remotely

• REST Server

Frameworks used

• construct - Binary parsing (https://construct.readthedocs.io/)

• cryptography - cryptography magic (https://cryptography.io/en/stable/)

• gevent - coroutines (http://www.gevent.org/)

• dpkt - pcap parsing (https://dpkt.readthedocs.io/en/latest/)

• Flask - REST API (https://pypi.org/project/Flask/)

Install

Via pip:

pip install xbox-smartglass-core

See the end of this README for development-targeted instructions.

How to use

There are several command line utilities to check out:

$ xbox-cli

Some functionality, such as GameDVR record, requires authentication with your Microsoft Account to validate you have the right to trigger such action.

To authenticate / get authentication tokens use:

$ xbox-authenticate

# Alternative: Use the ncurses terminal ui, it has authentication integrated
$ xbox-tui

REST Server

Start the REST server:

$ xbox-rest-server

For more information consult RestFAQ

Fallout 4 relay service

To forward the title communication from the Xbox to your local host to use third-party Fallout 4 Pip boy applications or extensions:

xbox-fo4-relay

Screenshots

Here you can see the SmartGlass TUI (Text user interface):

Development workflow

Ready to contribute? Here’s how to set up xbox-smartglass-core-python for local development.

1. Fork the xbox-smartglass-core-python repo on GitHub.

2. Clone your fork locally:

   $ git clone [e-mail]:your_name_here/xbox-smartglass-core-python.git

3. Install your local copy into a virtual environment. This is how you set up your fork for local development:

   $ python -m venv ~/pyvenv/xbox-smartglass
   $ source ~/pyvenv/xbox-smartglass/bin/activate
   $ cd xbox-smartglass-core-python
   $ pip install -e .[dev]

4. Setup auto-linting before each commit via pre-commit:

   $ pre-commit install

5. Create a branch for local development:

   $ git checkout -b name-of-your-bugfix-or-feature

6. Make your changes.

7. Before pushing the changes to git, please verify they actually work:

   $ pre-commit run -a
   $ pytest
   
   # For more extensive testing on several frameworks:
   $ tox

8. Commit your changes and push your branch to GitHub:

   $ git commit -m "Your detailed description of your changes."
   $ git push origin name-of-your-bugfix-or-feature

9. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. Code includes unit-tests.

2. Added code is properly named and documented.

3. On major changes the README is updated.

4. Run tests / linting locally before pushing to remote.

Credits

Kudos to joelday for figuring out the AuxiliaryStream / TitleChannel communication first! You can find the original implementation here: SmartGlass.CSharp.

This package uses parts of Cookiecutter and the audreyr/cookiecutter-pypackage project template.

History

1.2.0 (2020-03-04)

• CLI scripts rewritten, supporting log/loglevel args now, main script is called xbox-cli now

• Add REPL / REPL server functionality

• Updates to README and REST server documentation

1.1.2 (2020-02-29)

• Drop support for Python 3.5

• crypto: Fix deprecated cryptography functions

• tests: Speed up REST server tests (discovery, poweron)

• Update all dependencies

1.1.1 (2020-02-29)

• FIX: Include static files for REST server in distributable package

• REST: Remove deprecated packages from showing in /versions endpoint

1.1.0 (2020-02-29)

• Clean up dependencies

• Merge in xbox-smartglass-rest, deprecate standalone package

• Merge in xbox-smartglass-stump, deprecate standalone package

• Merge in xbox-smartglass-auxiliary, deprecate standalone package

• tui: Fix crash when bringing up command menu, support ESC to exit

1.0.12 (2018-11-14)

• Python 3.7 compatibility

1.0.11 (2018-11-05)

• Add game_dvr_record to Console-class

• Fix PCAP parser

• Add last_error property to Console-class

1.0.10 (2018-08-14)

• Safeguard around connect() functions, if userhash and xsts_token is NoneType

1.0.9 (2018-08-11)

• Fix for Console instance poweron

• Reset state after poweroff

• Little fixes to TUI

• Support handling MessageFragments

1.0.8 (2018-06-14)

• Use aenum library for backwards-compat with _enum.Flag_ on py3.5

1.0.7 (2018-05-16)

• CoreProtocol.connect: Treat ConnectionResult.Pending as error

• constants.WindowsClientInfo: Update ClientVersion 15 -> 39

• Make CoreProtocol.start_channel take optional title_id / activity_id arguments

1.0.1 (2018-05-03)

• First release on PyPI.