3. Python 3.6

Welcome to the Python on Windows tutorial. Below you will be able to run some basic examples, in Windows 10 and Python 3.6, to interface with your MetaSensor.

You are expected to have at least a basic understanding of Python as a language. There are many amazing websites such as https://www.learnpython.org/ to teach you if you are new to Python.

The Python SDK itself is a wrapper around the C++ SDK, calling into the C++ code using the ctypes library. You will want to keep a reference to the ctype documentation and C++ SDK documentation handy.

3.1. Prerequsites

You should have completed the instructions in the previous section related to the Windows Installation.

We will be using the Git Bash terminal to run the Python examples below.

First, let’s check that you have Python 3.6 installed:

  1. Open Git CMD or Windows Command Prompt

  2. Run the command

>>> which python3
_images/python3-1.jpg

If Python3 is not installed, use Visual Studio to install it:

_images/python3-2.jpg

Visual Studio installed Python3 in this directory on my machine (it may be different for you): C:/Program Files (x86)/Microsoft Visual Studio/Shared/Python36_64.

VS installed Python 3.6 but left the executable named python. Because I already had python2.7 installed and it is executed as python already, I had to manually rename the Python 3.6 executable to python3:

_images/python3-3.jpg

I also updated my environment variables:

_images/python3-4.jpg

3.1.1. Install Pip3

The package manager for python is pip. In Python 3 it is typically refered to pip3 and it is generally a soft link to pip. Essentially, pip = pip3.

Pip and Pip3 should be installed when Python 3 is installed and should be locatted in your Script directory: C:/path/to/python/Scripts/pip3.

_images/python3-6.jpg

Note

You should already have pip/pip3 installed (by Visual Studio). Please check this using the command which pip3 and if pip is missing, consult Visual Studio support here.

_images/python3-5.jpg

If you have Python 2 installed and you don’t want the pip packages to go into the Python 2 package manager folder, you need to make sure pip3 is properly installed and linked and that your environment variables point to the right Scripts directory.

3.1.2. Upgrade Pip3

It is essential that your pip be up to date. For good measure, run the commands below:

Warning

You may need to run this as sudo or administrator. In order to do this, right-click your shell and Run as administrator.

_images/python-0.jpg
>>> python3 -m pip install --upgrade pip
_images/python3-7.jpg

3.1.3. Install MetaWear

MetaWear is available on Pip. This means you can run the command below to install the MetaWear Python library directly:

>>>  pip3 install metawear
_images/python3-8.jpg

Please take a look at the official website for PyPi to learn more about the MetaWear package: https://pypi.org/project/metawear/

_images/python-12.jpg

3.1.4. Upgrade MetaWear

You may need to upgrade metawear. For good measure, always run:

>>> pip3 install metawear --upgrade
_images/python3-9.jpg

3.1.5. Download Examples

Head over to our Python Github page: https://github.com/mbientlab/MetaWear-SDK-Python

_images/python-6.jpg

You can clone the repository or simply download as a ZIP file:

>>>  git clone https://github.com/mbientlab/MetaWear-SDK-Python.git
_images/python-7.jpg

Make sure the MetaWear-SDK-Cpp submodule is also downloaded. If it is not present, use the command git clone --recurse-submodules https://github.com/mbientlab/MetaWear-SDK-Python

3.2. Scan and Connect

This tutorial will take you through your first MetaWear Python App.

Note

Make sure you have a MetaWear device with you, fully-charged, and that you have that device’s MAC address handy.

We will ignore most of the items in the Github repository for now and instead we will focus on the examples folder. Head over to the examples folder:

_images/python-8.jpg

Using your favorite editor, take a look at the scan_connect.py example.

This python code will scan for nearby Bluetooth devices and print out a list of available devices. You can then choose a device you want to connect to:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
print("scanning for devices...")
devices = {}
def handler(result):
    devices[result.mac] = result.name

BleScanner.set_handler(handler)
BleScanner.start()

sleep(10.0)
BleScanner.stop()

i = 0
for address, name in six.iteritems(devices):
    print("[%d] %s (%s)" % (i, address, name))
    i+= 1

msg = "Select your device (-1 to rescan): "
selection = int(raw_input(msg) if platform.python_version_tuple()[0] == '2' else input(msg))

Run the code:

>>>  # usage: python3 scan_connect.py
>>>  python3 scan_connect.py

Select the device you want to connect to. The MAC address for my favorite MetaSensor is D8:B5:11:21:96:06.

>>>  Select your device (-1 to rescan): 1

The code will then connect to this device for 5 seconds, retrieve device information, and disconnect.

_images/python3-11.jpg

As you can see, your Windows machine connected to the MetaSensor using Bluetooth and retrieved some information about the devices such as the firmware version and the manufacturer name.

Congratulations, you ran your first Python script!

3.3. Dealing with Errors

3.3.1. Errors

If you run into errors, it means you missed an installation step.

  1. Go back to the begining of this tutorial and re-install everything carefully.

  2. Try restarting your Bluetooth adapter by disabling it under the Device Manager (or by un-plugging your Bluetooth dongle if applicable).

  3. Try reseting or firmware updating your MetaSensor using the Android or iOS MetaBase App. This solves 99% of problems! See the troubleshooting section.

  4. Always try running the scan_connect.py example first. It is simple and will make sure everything is working properly on your system.

  5. Upgrade pip and metawear. Make sure Visual Studio is up to date as well.

3.3.2. Missing Modules

If you are missing modules, simply install them using pip:

>>> pip3 install [module name]
_images/python3-10.jpg

3.3.3. Sudo and Administrator

Sudo is a program for Unix-like computer operating systems that allows users to run programs with the security privileges of another user, by default the superuser.

Some setup might require that you run your scripts using sudo. If so, simply add sudo to the beggining of your python command sudo python scan_connect.py.

On Windows, you may need to run your Git or Cmd shell as administrator.

3.3.4. Running Python Scripts

Be sure you are running out scripts from a command line or GUI that can interpret and run Python.

Warning

DO NOT USE Git Bash to run your Python scripts.

Use Git CMD or the Windows Command Prompt or another acceptable shell to run your Python scripts.

Git Bash may not allow inputs and therefore will fail:

_images/python-28.jpg

Git CMD can execute Python scripts:

_images/python-27.jpg

The Windows Command Prompt can execute Python if you have followed the tutorial properly:

_images/python-29.jpg

3.3.5. Virtual Machines (VMs)

If you are running in a virtual environment, you will need to take extra care to make sure the Bluetooth drivers and adapters are working in the VM before you do anything else.

For example, VirtualBox guest OS doesn’t recognize the Bluetooth adapter by default. There are many great tutorials to get this working like this one here.

_images/vm-0.png

Steps you can take:

  1. Disable Bluetooth Adapter on Host OS

  2. Launch Guest OS

  3. Enable Bluetooth Adapter on Host OS

  4. Enable Bluetooth Adapter in the usb device list (Guest OS): Devices->usb->check my device

You may also need to install the VirtualBox extension Pack or similar support software, see more information here.

MbientLab is not responsible for VM support. Please consult the forum for the appropriate VM software you are using if you run into issues.

3.3.6. Documentation

As our Python API is based on the CPP library, we recommend that you have two documents open:

  1. The CPP documentation: https://mbientlab.com/cppdocs/latest

  2. The CPP API reference: https://mbientlab.com/documents/metawear/cpp/latest

3.4. Additional Examples

Please check out the Python2.7 section for additional examples or simply read through all of the Python scripts in the example folder.

3.5. Next steps

Start coding your own Python script!

Please read our C docs to learn about all of the capabilities of the MetaSensors: https://mbientlab.com/cppdocs/latest/index.html