Skip to content

Latest commit

 

History

History
103 lines (91 loc) · 5.17 KB

README.md

File metadata and controls

103 lines (91 loc) · 5.17 KB
Raw

Microsoft Band Python Library

good-idea-2-license made-with-python Code style: black

This library is currently just a side project to create a Python interface for the Microsoft Band and Microsoft Band 2.
It doesn't have any friendly UIs, so unless you like gettings your hands dirty (or reading my Python code) this probably isn't for you. Sorry.
I do have something in the works to enable interacting with a Band through Chromium though, stay tuned...

Supported Features

  • Communicating with a Band over Bluetooth
  • Communicating with a Band over USB
  • Communicating with a Band over BLE (partially)
  • Getting/setting Band time
  • Decoding/encoding Band RLE icons
  • Reading/setting the Me Tile (watchface background)
  • Reading tile icons (and default tiles)
  • Downloading device logs
  • Updating device firmware version
  • Parsing/building command packets
  • Parsing FirmwareUpdate.bin
  • Escaping demo mode
  • Entering demo mode (not recommended)
  • Escaping OOBE (on Band 2)
  • Customising profile (on Band 2)

Planned Features

  • Escaping OOBE (on Band 1)
  • Customising profile (on Band 1)
  • Customising tile layout
  • Customising colour scheme
  • Updating calendar items
  • Setting up custom workouts
  • Generating and uploading ephemeris data to reduce TTFF
  • Updating timezone info
  • Processing live data from sensors
  • Downloading and processing historical data
  • Framework for interactive tiles running from a computer
  • Shenanigans

Setting up a development environment

msband depends on poetry for building, construct+construct_typed for parsing/building data structures, bleak for BLE stuff, pyusb for USB stuff, and pillow for reading images.

Thankfully, Poetry takes care of setting up the virtual environment correctly, so here's the short set of instructions to get started:

  • Install Python 3.10 or higher
  • git clone git@github.com:hire-marat/msband.git --depth 1
  • cd msband
  • py -m pip install poetry
  • py -m poetry update
  • To get started, see the "Running the examples" section [anchor-link]

Setting up Bluetooth

on Windows

  • Pair the Band with your machine, making sure to press No when it prompts to use an iPhone/BLE
  • Run control printers to open the Devices and Printers
  • Find the MAC Address of your device in Properties -> Bluetooth -> Troubleshooting Information -> Unique identifier
  • Copy the BluetoothInterface example from examples/connect.py and replace BLUETOOTH_MAC_ADDRESS with the MAC Address of your device

Setting up Bluetooth Low Energy

on Windows

  • Pair the Band with your machine, making sure to press Yes when it prompts to use an iPhone/BLE
  • Run control printers to open the Devices and Printers
  • Find the public MAC Address of your device in Properties -> Connected Device -> Unique identifier
  • Copy the BLEv2Interface example from examples/connect.py and replace BLUETOOTH_MAC_ADDRESS with the public MAC Address of your device
  • Best run in a Python interpreter with a global await such as IPython in PyCharm

Setting up USB

on Linux

You probably already have libusb set up, and if that's the case, PyUSB will use it as a backend automatically.
If that's not the case, please research PyUSB compatibility with your distro.

For a Microsoft Band 1

  • Copy the USBInterface example from examples/connect.py
  • Replace USBInterface("") with USBInterface("", pid=0x02D7)

For a Microsoft Band 2

on Windows

For a Microsoft Band 1

  • Get libusb-win32 [sourceforge.net]
  • Open the Filter Wizard
  • Install a device filter for the vid:045e pid:02d7 WinUsb Device
  • Copy the USBInterface example from examples/connect.py
  • Replace USBInterface("") with USBInterface("", pid=0x02D7)

For a Microsoft Band 2

  • Get libusb-win32 [sourceforge.net]
  • Open the Filter Wizard
  • Install a device filter for the vid:045e pid:02d6 rev:0001 WinUsb Device
  • Copy the USBInterface example from examples/connect.py

Running the examples

  • Open an interpreter using the virtualenv set up by Poetry
    • You can:
      • Use your IDE's Python interpreter, making sure to set it to .venv\bin\python or .venv\Scripts\python.exe
      • Use IPython by running poetry run ipython
      • Use the Python interpreter by running poetry run python
  • Open examples/connect.py in a second window with a text editor
  • Open the example file you want to run in a third window with a text editor
  • Replace the code iband: ProtocolInterface = ... with the relevant connection code from examples/connect.py
  • Run the example code line by line in the Python interpreter

License

GOOD IDEA 2