GPIO Façade

A python wrapper for the Quanser HIL API that emulates the PyPi gpio and RPi.GPIO libraries.

The Quanser HIL API is recommended when writing code from scratch but the wrapper is provided as a convenience when there is an existing code base using the PyPi gpio or RPi.GPIO libraries.

However, unlike these libraries, this wrapper works on Windows with Quanser devices that support general-purpose digital I/O, such as the Quanser Mechatronic Sensors Trainer USB device. It is designed to be very similar to the PyPi gpio and RPi.GPIO libraries, but it is not a drop-in replacement because the board must be identified.

For RPi.GPIO, simply replace the line:

>>> import RPi.GPIO as GPIO

with:

>>> import quanser.hardware.gpio as GPIO

and add code to open the board. For example:

>>> GPIO.open("mech_sensors_trainer_usb")

Note that the GPIO.cleanup function must be called to clean up resources when the GPIO are no longer being used.

When using PyPi gpio to emulate RPi.GPIO, simply replace the line:

>>> import gpio as GPIO

with:

>>> import quanser.hardware.gpio as GPIO

and add code to open the board. For example:

>>> GPIO.open("mech_sensors_trainer_usb", "0")

Note that the GPIO.cleanup function must be called to clean up resources when the GPIO are no longer being used.

If the PyPi gpio library is being used with the GPIOPin class instead, then replace the line:

>>> import gpio

with:

>>> import quanser.hardware.gpio

and add code to open the board. For example:

>>> gpio.open("mech_sensors_trainer_usb", "0")

Note that the gpio.cleanup function should be called to clean up resources when the GPIO are no longer being used.

It should be possible to use this python wrapper on Linux systems with the Quanser SDK or QUARC installed as well.

quanser.hardware.gpio.BCM: int = 11: Use Broadcom numbering. This option is only provided for compatibility with the RPi.GPIO library.

quanser.hardware.gpio.BOARD: int = 10: Use board numbering. This option is only provided for compatibility with the RPi.GPIO library.

class quanser.hardware.gpio.GPIOPin(channel, direction=None, initial=0)

Bases: object

__init__(channel, direction=None, initial=0)

Constructs a GPIOPin instance.

NOTE: Before this class is used, the module open() method must be called to identify the board being used.

Parameters

channel (int) – The channel number for the GPIO pin.
direction ([IN, OUT, None]) – The direction for the pin.
initial ([LOW, HIGH, None]) – The initial state for the pin.

Example

Get GPIO pin 2 of the Quanser Mechatronic Sensors Trainer USB device configured as an output that is initially low.

>>> import quanser.hardware.gpio as gpio
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     pin = gpio.GPIOPin(2, gpio.OUT, gpio.LOW)
>>>     ...
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

cleanup()

Cleans up any resources used. It does not reset the pin as an input.

Example

>>> import quanser.hardware.gpio as gpio
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     output_pin = gpio.GPIOPin(2, gpio.OUT, gpio.LOW)
>>>     try:
>>>         ...
>>>     finally:
>>>         output_pin.cleanup()
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

get_direction()

Gets the direction of the GPIO pin.

Returns: The direction of the GPIO pin as either IN or OUT.
Return type: int

Example

>>> import quanser.hardware.gpio as gpio
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     pin = gpio.GPIOPin(2)
>>>
>>>     direction = pin.get_direction()
>>>     print(f"direction = {'OUT' if direction == gpio.OUT else 'IN'}")
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

read()

Reads the value of the GPIO pin.

Returns: The value read as either LOW (0) or HIGH (1) indicating the state of the channel.
Return type: [LOW, HIGH]
Raises: HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Read from pin 1 of the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as gpio
>>> import time
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     input_pin = gpio.GPIOPin(1, gpio.IN)
>>>     while True:
>>>         state = input_pin.read()
>>>         print(f"GPIO: {state}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

set_direction(direction)

Sets the direction of the GPIO pin.

Parameters: direction ([IN, OUT]) – The direction to which to configure the GPIO. It must be either IN or OUT.
Raises: HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Write to pin 2 and read from pin 1 of the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as gpio
>>> import time
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     output_pin = gpio.GPIOPin(2)
>>>     input_pin  = gpio.GPIOPin(1)
>>>
>>>     output_pin.set_direction(gpio.OUT)
>>>     input_pin.set_direction(gpio.IN)
>>>
>>>     toggle = gpio.HIGH
>>>     while True:
>>>         output_pin.write(toggle)
>>>         toggle = gpio.HIGH if toggle == gpio.LOW else gpio.LOW
>>>
>>>         state = input_pin.read()
>>>         print(f"GPIO: {state}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

setup(direction=None, initial=0)

Sets up whether the channel is an input or an output.

Parameters

direction ([IN, OUT]) – The direction to which to configure the GPIO. It must be either IN or OUT.
initial ([LOW, HIGH, None]) – The initial value to which to set the GPIO.

Raises

HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Write to pin 2 and read from pin 1 of the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as gpio
>>> import time
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     output_pin = gpio.GPIOPin(2)
>>>     input_pin  = gpio.GPIOPin(1)
>>>
>>>     output_pin.setup(gpio.OUT, gpio.LOW)
>>>     input_pin.setup(gpio.IN)
>>>
>>>     toggle = gpio.HIGH
>>>     while True:
>>>         output_pin.write(toggle)
>>>         toggle = gpio.HIGH if toggle == gpio.LOW else gpio.LOW
>>>
>>>         state = input_pin.read()
>>>         print(f"GPIO: {state}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

write(value)

Writes the value of the GPIO pin.

Parameters: state ([LOW, HIGH]) – The state to write to the channel.
Raises: HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Write to pin 2 and read from pin 1 of the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as gpio
>>> import time
>>>
>>> gpio.open("mech_sensors_trainer_usb")
>>> try:
>>>     output_pin = gpio.GPIOPin(2, gpio.OUT, gpio.LOW)
>>>     input_pin  = gpio.GPIOPin(1, gpio.IN)
>>>
>>>     toggle = gpio.HIGH
>>>     while True:
>>>         output_pin.write(toggle)
>>>         toggle = gpio.HIGH if toggle == gpio.LOW else gpio.LOW
>>>
>>>         state = input_pin.read()
>>>         print(f"GPIO: {state}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")

quanser.hardware.gpio.HIGH: int = 1: High value for a GPIO.

quanser.hardware.gpio.IN: int = 1: Indicate that the GPIO is an input pin.

quanser.hardware.gpio.LOW: int = 0: Low value for a GPIO.

quanser.hardware.gpio.OUT: int = 0: Indicate that the GPIO is an output pin.

quanser.hardware.gpio.cleanup(channels=None)

Cleans up any resources used and resets any pins used to inputs.

Parameters: channels (list) – A list of channels to reset to inputs. Any channels not in this list will be left unchanged. If this parameter is omitted or None then all channels used will be reset to inputs. To avoid reseting any pins to inputs, pass an empty list.
Raises: HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Cleanup after opening the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as GPIO
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     ...
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.getmode()

Gets the numbering system for GPIO numbers.

Returns: The numbering mode to use for the GPIO numbers.
Return type: [BOARD, BCM, None]

Example

>>> import quanser.hardware.gpio as GPIO
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     mode = GPIO.getmode() # returns GPIO.BOARD, GPIO.BCM or None (if never set)
>>>     ...
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.input(channel)

Reads the value of a GPIO pin.

NOTE: Before any function is called in this module, the open() method must be called to identify the board being used.

Parameters: channel ([list, int]) – The channel number to read or a list of channels to read.
Returns: The value read as either LOW (0) or HIGH (1) indicating the state of the channel. It will be a list of binary values if the channel parameter is a list of channels.
Return type: [LOW, HIGH, list]
Raises: HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Read from GPIO channels 0 to 3 of the Quanser Mechatronic Sensors Trainer USB device and print the states every second.

>>> import quanser.hardware.gpio as GPIO
>>> import time
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     while True:
>>>         states = GPIO.input([0, 1, 2, 3])
>>>         print(f"GPIO: {states[0]} {states[1]} {states[2]} {states[3]}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.open(board_type, board_identifier='0')

Opens a board based on its type and identifier.

Parameters

board_type (string) – A string identifying the type of board to open. For example, “mech_sensors_trainer_usb” is the board type for the Quanser Mechatronic Sensors Trainer USB device.
board_identifier (string) – A string distinguishing between multiple boards of the same type. This parameter is typically a board number as a string, such as “0”, but it may also be a serial number. The default value is “0”.

Raises

HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Open the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as GPIO
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     ...
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.output(channel, state)

Writes the value of a GPIO pin.

NOTE: Before any function is called in this module, the open() method must be called to identify the board being used.

Parameters

channel ([list, int]) – The channel number to read or a list of channels to read.
state ([list, LOW, HIGH]) – The state to write to the channel or a list of states to write.

Raises

HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Write to GPIO 2 of the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as GPIO
>>> import time
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     GPIO.setup(2, GPIO.OUT)
>>>     toggle = GPIO.HIGH
>>>     while True:
>>>         GPIO.output(2, toggle)
>>>         toggle = GPIO.HIGH if toggle == GPIO.LOW else GPIO.LOW
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.read(channel)

Reads the value of a GPIO pin.

NOTE: Before any function is called in this module, the open() method must be called to identify the board being used.

Parameters: channel ([list, int]) – The channel number to read or a list of channels to read.
Returns: The value read as either LOW (0) or HIGH (1) indicating the state of the channel. It will be a list of binary values if the channel parameter is a list of channels.
Return type: [LOW, HIGH, list]
Raises: HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Read from GPIO channels 0 to 3 of the Quanser Mechatronic Sensors Trainer USB device and print the states every second.

>>> import quanser.hardware.gpio as GPIO
>>> import time
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     while True:
>>>         states = GPIO.read([0, 1, 2, 3])
>>>         print(f"GPIO: {states[0]} {states[1]} {states[2]} {states[3]}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.setmode(mode)

Sets the numbering system for GPIO numbers.

This method does nothing because Quanser devices do not use different numbering schemes but the mode will be stored so that getmode returns the configured value.

Parameters: mode ([BOARD, BCM, None]) – The numbering mode to use for the GPIO numbers.

Example

>>> import quanser.hardware.gpio as GPIO
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     GPIO.setmode(GPIO.BOARD)
>>>     ...
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.setup(channel, direction, initial=None)

Sets up whether the channel is an input or an output.

NOTE: Before any function is called in this module, the open() method must be called to identify the board being used.

Parameters

channel (int) – The channel number of the GPIO to configure.
direction ([IN, OUT, None]) – The direction to which to configure the GPIO.
initial ([LOW, HIGH, None]) – The initial value to which to set the GPIO.

Raises

HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Write to GPIO 2 and read from GPIO 1 of the Quanser Mechatronic Sensors Trainer USB device and print the states every second.

>>> import quanser.hardware.gpio as GPIO
>>> import time
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     GPIO.setup([1, 2], [GPIO.IN, GPIO.OUT])
>>>     toggle = GPIO.HIGH
>>>     while True:
>>>         GPIO.output(2, toggle)
>>>         toggle = GPIO.HIGH if toggle == GPIO.LOW else GPIO.LOW
>>>
>>>         states = GPIO.input([1, 2])
>>>         print(f"GPIO: {states[0]} {states[1]}")
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")
>>> finally:
>>>     GPIO.cleanup()

quanser.hardware.gpio.write(channel, state)

Writes the value of a GPIO pin. This method is an equivalent alternative to the output method.

NOTE: Before any function is called in this module, the open() method must be called to identify the board being used.

Parameters

channel ([list, int]) – The channel number to read or a list of channels to read.
state ([list, LOW, HIGH]) – The state to write to the channel or a list of states to write.

Raises

HILError – Raised when an error occurs. A suitable error message may be retrieved using get_error_message.

Example

Write to GPIO 2 of the Quanser Mechatronic Sensors Trainer USB device.

>>> import quanser.hardware.gpio as GPIO
>>> import time
>>>
>>> GPIO.open("mech_sensors_trainer_usb")
>>> try:
>>>     GPIO.setup(2, GPIO.OUT)
>>>     toggle = GPIO.HIGH
>>>     while True:
>>>         GPIO.write(2, toggle)
>>>         toggle = GPIO.HIGH if toggle == GPIO.LOW else GPIO.LOW
>>>         time.sleep(1)
>>> except KeyboardInterrupt:
>>>     print("\nExiting...")
>>> finally:
>>>     GPIO.cleanup()