godirect-examples

Official examples for Vernier Go Direct® Sensors in both Python and JavaScript

This project is maintained by VernierST

Getting Started with Vernier Go Direct® Sensors and Python

This guide shows you how to get started writing Python programs for your Vernier Go Direct sensors. The guide contains the following topics:

If you are new to Python you should look over all of the steps. If you are familiar with Python you might just focus on installing the godirect module and downloading the examples.

Getting Started Requirements

We have developed a Python module called godirect that allows you to communicate with Vernier Go Direct sensors via USB or Bluetooth Low Energy (BLE). This requires the following:

Install Python 3

The godirect module is designed to work with Python 3, it is not compatible with Python 2. In some cases, Python is pre-installed and shipped with your operating system. Use the following steps to check for Python 3 on your machine, and to install Python 3 if needed:

Choose an IDE

With Python installed, you need to choose an application that you will use to write and run your Python programs. You can write your programs in a simple text or code editor, or you can use an Integrated Development Environment (IDE). An IDE is a software application that provides all of the tools to write, comment, edit, debug, develop and run software programs. Python has an IDE bundled with it called IDLE that is cross-platform, and suitable for beginners. If you are new to Python and programming, we recommend that you start with this tool.

Later, you may want to research the various IDEs, learn about the different features, and give one a try. For example, Visual Studio Code is a free IDE available for Windows, Linux, and Mac. There are many other choices, and you can find more information at python.org

Install the Vernier godirect Module

Once you have Python 3 installed, you will use a tool called pip (a Python 3 package manager) to install the godirect module and other Python modules that you may need. Python automatically includes pip, so this tool is ready to use. Note that we will be using the pip3 command, rather than just pip, to ensure that the Vernier files will be associated with Python 3, and not Python 2.

The pip3 commands are executed by running them in your operating systems’ tool for executing commands (Powershell, Command Prompt, or Terminal window). There are slight differences in the required steps to install the godirect module for Windows, macOs, and Linux (including Linux running on Raspberry Pi). Follow the steps outlined below for your platform.

Windows

Run the following command in Powershell or Command Prompt to install the godirect module for USB and BLE:

pip3 install godirect[USB,BLE]

If you received an error, read below the next pip3 command for a possible solution. If there was no error, then the next step is to install a module called Bleak. This module is required to support communication through your computer’s Bluetooth radio. Bleak is installed by running the following command:

pip3 install bleak

If you received an error during the installation of godirect, part of which looks like the message below, it is probably because your Windows system does not have the appropriate compiler. The godirect module includes a package that requires a C++ compiler.

C++ error message

In order to install without this failure, you will need to follow the instructions to download and install the command line Build Tools for Visual Studio. The latest version of the tools download can be found by scrolling down to the All Downloads section and expanding Tools for Visual Studio (as shown in the figure below). After completing the installation of this tool repeat the pip3 installation steps for godirect and Bleak.

MSVC Tools Download

Mac

Run the following command in Terminal to install the godirect module for USB and BLE:

pip3 install godirect[USB,BLE]

BLE support on Mac is currently only with the use of a Bluegiga BLED112 Bluetooth® Low Energy Dongle. You will need this dongle if you wish to talk to the Go Direct sensors via BLE.

Linux (and Linux on Raspberry Pi)

Run the following command in your terminal to install the godirect module for USB and BLE:

pip3 install godirect[USB,BLE]

Some Linux distributions will not include all of the tools required by the godirect module and its dependencies. If you see errors when you run the pip3 install, you might need to first install the two packages as shown below, before trying again:

sudo apt install libusb1.0.0

sudo apt install libudev-dev

In order to support communication through your computer’s Bluetooth radio, a module called Bleak must be installed by running the following command in your terminal:

pip3 install bleak

In order to communicate with Go Direct devices over USB on Linux systems, you will need to provide a special udev rule that allows the device to be identified when it is plugged in. The rule file is located on our github directory. Use the following steps to download the rule file and then move it to the proper location:

Confirm Installation of the godirect Module

At this point, you should have Python 3 installed and have the godirect module installed. Before moving to examples, confirm the installation of the godirect module by showing the version information. Run the following command in the terminal:

pip3 show godirect

Running the pip3 show command will provide information about the installed package, including the version number. Should you need to update to a newer version in the future, run the following command in the terminal:

pip3 install godirect --upgrade

Download and Run an Example

With the godirect module installed, it is time to run an example.

Clone godirect-examples

About the Getting Started Examples

The getting started examples demonstrate how to collect data from Go Direct sensors. Under the hood, these examples all use the godirect module to communicate with the Go Direct devices. However, to make things a bit simpler, we created a layer to abstract some of the details away and provide some simple functions. That layer is named gdx and can be found in the /gdx/ folder (note that this folder must be located in the same directory as the examples or programs that you write that use the gdx functions). All of the getting started examples make use of this layer for a cleaner, simpler entry point into coding with Go Direct devices.

The gdx functions used in a typical program to collect data include:

A simple program using the gdx module looks like this:

from gdx import gdx
gdx = gdx.gdx()
 
gdx.open_usb()
gdx.select_sensors()
gdx.start() 
 
for i in range(0,5):
    measurements = gdx.read()
    if measurements == None: 
        break 
    print(measurements)
 
gdx.stop()
gdx.close()

Notes Regarding the gdx Functions

Here is some more information about the gdx functions, including how you might add arguments to a few of the functions:

from gdx import gdx
gdx = gdx.gdx()

gdx.open_usb()

gdx.open_ble()

gdx.select_sensors()

gdx.start()

measurements = gdx.read()

gdx.stop()

gdx.close()

As stated earlier, these gdx functions are available in the gdx.py file, in the gdx folder. The gdx.py file is easy to locate and available for you to modify. Consider adding your own functions, or modifying the functions to meet your needs.

Troubleshooting and Notes

Support

Python

Pip

Bluetooth

Installing Python on Windows

Python3 Modify

Python 3 Next

Python 3 Install

error: option --single-version-externally-managed not recognized

This is a known incompatibility and the options to work around it are described here: https://github.com/hbldh/bleak/issues/147

License

All of the content in this repository is available under the terms of the BSD 3-Clause License.

Vernier products are designed for educational use. Our products are not designed nor are they recommended for any industrial, medical, or commercial process such as life support, patient diagnosis, control of a manufacturing process, or industrial testing of any kind.