Skip to main content

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

Project description

Xbox-Smartglass-Core

PyPi version Docs Build status Discord chat

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

Major frameworks used

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

REST server

Start the server daemon

Usage information

Example localhost:

# Serve on '127.0.0.1:5557'
$ xbox-rest-server
INFO:     Started server process [927195]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:5557 (Press CTRL+C to quit)

Example local network:

192.168.0.100 is the IP address of your computer running the server:

xbox-rest-server --host 192.168.0.100 -p 1234
INFO:     Started server process [927195]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://192.168.0.100:1234 (Press CTRL+C to quit)

REST API

Since the migration from Flask framework to FastAPI, there is a nice OpenAPI documentation available:

http://{IPAddress}:{port}/docs

Authentication

If your server runs on something else than 127.0.0.1:5557 or 127.0.0.1:8080 you need to register your own OAUTH application on Azure AD and supply appropriate parameters to the login-endpoint of the REST server.

Check out: https://github.com/OpenXbox/xbox-webapi-python/blob/master/README.md

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):

TUI list TUI console TUI log TUI log detail

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 git@github.com:your_name_here/xbox-smartglass-core-python.git
  1. 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]
  1. Create a branch for local development::
git checkout -b name-of-your-bugfix-or-feature
  1. Make your changes.

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

pytest
  1. 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
  1. 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

CHANGELOG

1.3.0 (2020-11-02)

  • Drop Python 3.6 support
  • Deprecate Authentication via TUI
  • Major rewrite (Migration from gevent -> asyncio)
  • Rewrite of REST Server (Migration FLASK -> FastAPI)
  • Adjust to xbox-webapi-python v2.0.8
  • New OAUTH login flow

1.2.2 (2020-04-03)

  • Fix: Assign tokenfile path to flask_app (aka. REST server instance)

1.2.1 (2020-03-04)

  • cli: Python3.6 compatibility change
  • HOTFIX: Add xbox.handlers to packages in setup.py

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for xbox-smartglass-core, version 1.3.0
Filename, size File type Python version Upload date Hashes
Filename, size xbox_smartglass_core-1.3.0-py2.py3-none-any.whl (85.7 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size xbox-smartglass-core-1.3.0.tar.gz (395.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page