API Reference¶

ADC¶

class mpio.ADC(device)¶

Bases: object

An Analog to Digital Converter (ADC) object to configure and read ADC values.

Once an ADC device has been identified, channels on that device can be configured to trigger by hardware or software to generate digital values from analog inputs.

Parameters:	device (int) – The ADC device.

device¶

Device ID of the ADC.

Type:	int

name¶

Linux name of the ADC device.

Type:	str

value(channel)¶

Perform a software trigger and get the raw ADC value.

Calling this function causes a software trigger of the ADC. The ADC will do a conversion and then return the value.

Parameters:	channel (int) – The ADC channel.
Returns:	int

scale¶

Get the ADC value scale.

The value you have to multiply the ADC value by to get microvolts.

Type:	float, None

microvolts(channel)¶

Perform a software trigger and get the microvolts value.

The same as calling value(channel) * scale().

Returns:	float

volts(channel)¶

Perform a software trigger and get the volts value.

The same as calling value(channel) * scale / 1000.0.

Returns:	float

available_channels¶

Get a list of available channels for the device.

Type:	list: A list of channel ids available.

available_triggers¶

List of available trigger names for the device.

One of the names returned here can then be used when calling start_capture() to specify the trigger.

Type:	list: A list of trigger names available.

start_capture(channels, trigger, buffer_size=100)¶

Start a capture.

Examples

The typical usage example for performing a triggered capture is as follows.

>>> a.start_capture()
>>> while CONDITION: data = a.get_capture()
>>> a.stop_capture()

Parameters:	channels (list) – Array of channels to capture for. trigger (str) – The trigger to be used. buffer_size (int) – The buffer size to store.

get_capture(timeout=None)¶

Block for up to the specified timeout and read the capture data.

Parameters:	timeout (int, float, None) – timeout duration in seconds.

stop_capture()¶: Stop any pending capture.

async_start_capture(channels, trigger, callback, buffer_size=100)¶

Returns a thread that invokes the specified callback when data is captured asynchronously.

Parameters:	channels (list) – Array of channels to capture for. trigger (str) – The trigger to be used. buffer_size (int) – The buffer size to store. callback – Function to call when interrupt occurs.
Returns:	thread

sampling_frequency¶

Get the sampling frequency of the ADC.

Type:	int

close()¶: Close the device and release any system resources.

static enumerate()¶

Enumerate a list of ADC devices available on the system.

Returns:	list

DevMem¶

class mpio.DevMem(addr, filename='/dev/mem')¶

Bases: object

Object to manage memory at the specified address.

Provides an interface to read/write raw memory, like hardware registers.

This allows you, for example, to manually shortcut any software and manually read and write hardware registers. This can be useful for debugging, but also useful for trivial setup and operation of hardware that is otherwise not exposed through a formal driver.

See also

This is losely similar in capability to the userspace command line tool devmem2.

Note

Running this requires root access by default.

Note

This interface only maps one page at a time.

Warning

Use with extreme caution. This can make the system unstable, especially when changing values in memory that currently running code (like the kernel itself) is using. There is no error checking on values written.

Parameters:	addr (int) – The starting address to manage. filename (str) – The filename to mmap().

MODE8 = 1¶

MODE16 = 2¶

MODE32 = 4¶

read(offset, mode=4)¶

Read a value to the offset provided.

Parameters:	offset (int) – The offset from the base address. mode (int) – The mode of value.
Returns:	int

write(offset, value, mode=4)¶

Write a value to the offset provided.

Parameters:	offset (int) – The offset from the base address. value (int) – The value to be written. mode (int) – The mode of value.

fd¶

File descriptor of the underlying file.

Type:	int

addr¶

Base address of the memory.

Mode:	int

filename¶

Filename of the device mmap’d.

Mode:	str

close()¶: Close the device and release any system resources.

static write_reg(addr, value)¶: Utility function to write a 32 bit value.

static read_reg(addr)¶: Utility function to read a 32 bit value.

GPIO¶

class mpio.GPIO(pin, mode, initial=False, force_own=False)¶

Bases: object

Create a GPIO object to control and monitor an input or output pin.

Provides an interface to configure and use pins as general purpose digital inputs and outputs.

Pin Numbering Scheme: This interface uses pin numbers to identify pins that range from 0 to N. The pin numbering scheme involves groups of 32 pins. The first group is ‘A’, the second group is ‘B’, and so on. So, pin 0 is effectively A0. Pin 32 is B0, and so on. This means if you want to use CPU pin PD15, you would use pin number ((‘D’-‘A’) * 32) + 15 = 111 where ASCII ‘D’ - ‘A’ = 3.

Warning

Because internally the mode is set and then the value is set, there may be a flicker of the unintended value while configuring the pin.

Parameters:

pin (int) – The pin number of the GPIO.
mode (GPIO.IN, GPIO.OUT) – The mode of the GPIO. None for don’t change.
initial (GPIO.LOW, GPIO.HIGH, bool) – When the mode is GPIO.OUT, this will be the initial value of the output.
force_own (bool) – When True, steal ownership as necessary. However, this means that multiple objects are potentially controlling the pin.

IN = 'in'¶: Mode defines to specify the direction of the pin.

OUT = 'out'¶: Mode defines to specify the direction of the pin.

LOW = False¶: Easy to use defines for the state of an input or output pin.

HIGH = True¶: Easy to use defines for the state of an input or output pin.

RISING = 'rising'¶: Defines for the edge interrupt type of the pin.

FALLING = 'falling'¶: Defines for the edge interrupt type of the pin.

BOTH = 'both'¶: Defines for the edge interrupt type of the pin.

fd¶

Get the file descriptor of the underlying gpio value file.

Type:	int

pin¶

GPIO pin number.

Type:	int

name¶

GPIO pin name.

Type:	str

interrupts_available¶

Whether or not this GPIO supports edge interrupts.

Type:	bool

close()¶: Close the device and release any system resources.

mode¶

The mode of the pin.

Type:	bool

get()¶

Read the boolean value of the pin.

Note

This is really only valuable if the pin is actually configured as an input.

Returns:	bool

set(value)¶: Set the boolean output value of the pin.

Note

This is really only valuable if the pin is actually configured as an output.

input()¶: This is an alias for get().

output(value)¶: This is an alias for set(value).

poll(edge='both', timeout=-1)¶

Block and wait for an edge interrupt or the timeout to occur.

Parameters:	edge (GPIO.RISING, GPIO.FALLING, GPIO.BOTH, str) – The edge to interrupt on. timeout (int, float) – timeout duration in seconds.
Returns:	value if an edge event occurred, `None` on timeout.
Return type:	mixed

static pin_to_name(pin)¶

Lookup the name of a pin.

Returns:	Returns the pin name or None.
Return type:	str

static enumerate()¶

Enumerate a list of gpio pins available on the system.

Returns:	list

I2C¶

class mpio.I2C(devpath)¶

Bases: object

Interface to I2C buses available on the system. This interface only supports being a master.

The I2C bus dev must exist at some path like /dev/i2c-0. With that, this API can be used to communicate to any slave device connected to that bus. To communicate with the slave you must know the slave address and the format of messages the slave device expects. There is no slave device driver involved, so you have to manually communicate with the device.

Parameters:	devpath (str) – Complete path to the I2C device.

fd¶

File descriptor of the underlying file.

Type:	int

transfer(addr, messages)¶

Transfer messages to the specified I2C slave addr. Modifies the messages array with the results of any read transactions.

Parameters:	addr (int) – I2C address. messages (list) – list of I2C.Message messages.
Raises:	`TypeError` – if messages type is not list. `ValueError` – if messages length is zero, or if message data is not valid bytes.

close()¶: Close the device and release any system resources.

devpath¶

Path to the spidev.

Returns:	str

class Message(data, read=False, flags=0)¶

Bases: object

Instantiate an I2C Message object.

Parameters:	data (bytes, bytearray, list) – a byte array or list of 8-bit integers to write. read (bool) – specify this as a read message, where data serves as placeholder bytes for the read. flags (int) – additional i2c-dev flags for this message.
Returns:	Message object.
Return type:	Message
Raises:	`TypeError` – if data, read, or flags types are invalid.

SMBus¶

class mpio.SMBus(devpath)¶

Bases: object

SMBus object that opens the I2C device at the specified path.

Similar to the I2C class, this provides simple System Management Bus (SMB) communications for performing byte and block transfers.

See also

For an alternate package for interfacing with smbus devices, see smbus-cffi.

Parameters:	devpath (str) – Complete path to the I2C device.

fd¶

File descriptor of the underlying file.

Type:	int

devpath¶

Path to the spidev.

Returns:	str

write_byte(addr, command, value)¶

Write a byte of data.

Parameters:	addr (int) – 7-bit slave address.

read_byte(addr, command)¶

Read a byte of data.

Parameters:	addr (int) – 7-bit slave address.

close()¶: Close the device and release any system resources.

Input¶

class mpio.Input(name)¶

Bases: object

Input object to receive input device events.

Provides an interface to input subsytem devices available on the system. For example, a mouse or keyboard or gpio buttons can generate input events this interface can relay.

See also

For a more complete way to read linux input events, see the evdev package.

Parameters:	name (str) – For valid values of name, call enumerate().

TYPE_EV_SYN = 0¶

TYPE_EV_KEY = 1¶

TYPE_EV_REL = 2¶

TYPE_EV_ABS = 3¶

TYPE_EV_MSC = 4¶

TYPE_EV_SW = 5¶

TYPE_EV_LED = 17¶

TYPE_EV_SND = 18¶

TYPE_EV_REP = 20¶

TYPE_EV_FF = 21¶

TYPE_EV_PWR = 22¶

TYPE_EV_FF_STATUS = 23¶

name¶

The name identifier for the device.

Type:	str

close()¶: Close the device and release any system resources.

read()¶

Perform a blocking read forever until an event is returned or an error occurs.

Returns:	(tv_sec, tv_usec, evtype, code, value)

static enumerate()¶

Enumerate a list of input event devices available on the system.

Returns:	list

static desc(name)¶

Get the human readable description of the input device.

Returns:	str

driver_version¶

Get the driver version of the device.

Type:	str

device_id¶

Get the device id.

Type:	str

LED¶

class mpio.LED(name, value=None)¶

Bases: object

LED object using the specified LED name.

To determine what LED names are available on the system, the enumerate() function will return a list. That name can then be used to contruct an LED object and control the LED.

Note

In the case of a single physical RGB LED, this will usually show up as 3 different LEDs in this interface. This allows you to set the appropriate and independent R-G-B brightness values.

Note

This API should not be confused with just connecting up a physical LED to a gpio. This is not a generic interface for working with any LED. Unless you configure an LED in the Linux LED subsystem using Device Tree or hard coded setup, that LED won’t show up to this module. For that, you shoud use the GPIO class.

Parameters:	name (str) – The name of the LED. For valid values, call enumerate(). value (int, bool) – The brightness value or `True` for max brightness and `False` for off.

name¶: The LED name.

max_brightness¶

Maximum brightness value supportd by the LED.

Returns:	int

write(value)¶

Set the output brightness of the LED.

Parameters:	value (int, bool) – The brightness value or `True` for max brightness and `False` for off.

read()¶

Get the output brightness of the LED.

Returns:	int

brightness¶

Get the output brightness of the LED.

Returns:	int

close()¶: Close the device and release any system resources.

static enumerate()¶

Enumerate a list of LED names available on the system.

Returns:	list

PWM¶

class mpio.PWM(chip, channel, period=None, duty_cycle=None, enable=True, polarity=None, force_own=False)¶

Bases: object

Pulse Width Modulation (PWM) object to generate signals on a pin.

Provides an interface to Pulse Width Modulation (PWM) generators available on the system.

To identify a specific PWM instance, a chip number and channel number is needed. The available chips can be retrieved with the enumerate() function. Then, with that you can call num_channels() to see how many channels the chip supports. However, you will have to reference CPU and board documentation to find out what physical pin the chip/channel number corresponds to.

Parameters:

chip (int) – For valid values of chip, call enumerate().
channel (int) – For valid range of channel, call num_channels().
period (int) – Microsecond period value that is the sum of the active and inactive time.
duty_cycle (int, float) – Percent of period between 0.0 and 1.0.
enable (bool) – Enable the PWM output after setup.
polarity (self.NORMAL, self.INVERSED, None) – Polarity of the output.
force_own (bool) – When True, steal ownership as necessary. However, this means that multiple objects are potentially controlling the channel.

NORMAL = 'normal'¶

INVERSED = 'inversed'¶

chip¶

The PWM chip.

Type:	int

channel¶

The PWM chip channel.

Type:	int

enabled¶

Enabled property of the PWM.

Type:	bool

duty_cycle¶

Duty cycle of the PWM.

Type:	float

period¶

Microsecond period of the PWM.

Type:	int

close()¶: Close the channel and release any system resources.

polarity¶

Polarity setting of the PWM.

Basically, this sets the “active high” or “active low” setting of the PWM.

Type:	PWM.NORMAL, PWM.INVERSED

Note

This a readonly property because we set polarity in creation and there seems to be little value in changing it later.

static enumerate()¶

Enumerate a list of PWM chips available on the system.

Returns:	list

static num_channels(chip)¶

Get the number of available PWM channels on the specified chip.

Parameters:	chip (int) – The PWM chip id.
Returns:	int

SPI¶

class mpio.SPI(devpath, mode, max_speed, bit_order='msb', bits_per_word=8, extra_flags=0)¶

Bases: object

Instantiate a SPI object and open the spidev device at the specified path with the specified SPI mode, max speed in hertz, and the defaults of “msb” bit order and 8 bits per word.

The SPI bus dev must exist at some path like /dev/spidev0. With that, this API can be used to communicate to any device connected to that bus.

Note

This requires the kernel module spidev to be available.

See also

For an alternate package for interfacing with SPI devices, see spidev.

Parameters:	devpath (str) – spidev device path. mode (int) – SPI mode, can be 0, 1, 2, 3. max_speed (int, float) – maximum speed in Hertz. bit_order (str) – bit order, can be “msb” or “lsb”. bits_per_word (int) – bits per word. extra_flags (int) – extra spidev flags to be bitwise-ORed with the SPI mode.
Raises:	`TypeError` – if devpath, mode, max_speed, bit_order, bits_per_word, or extra_flags types are invalid. `ValueError` – if mode, bit_order, bits_per_word, or extra_flags values are invalid.

transfer(data)¶

Shift out data and return shifted in data.

Parameters:	data (bytes, bytearray, list) – a byte array or list of 8-bit integers to shift out.
Returns:	data shifted in.
Return type:	bytes, bytearray, list
Raises:	`TypeError` – if data type is invalid. `ValueError` – if data is not valid bytes.

close()¶: Close the device and release any system resources.

fd¶

File descriptor of the underlying file.

Type:	int

devpath¶

Get the device path of the underlying spidev device.

Type:	str

mode¶

Get or set the SPI mode. Can be 0, 1, 2, 3.

Raises:	`TypeError` – if mode type is not int. `ValueError` – if mode value is invalid.
Type:	int

max_speed¶

Get or set the maximum speed in Hertz.

Raises:	`TypeError` – if max_speed type is not int or float.
Type:	int, float

bit_order¶

Get or set the SPI bit order. Can be “msb” or “lsb”.

Raises:	`TypeError` – if bit_order type is not str. `ValueError` – if bit_order value is invalid.
Type:	str

bits_per_word¶

Get or set the SPI bits per word.

Raises:	`TypeError` – if bits_per_word type is not int. `ValueError` – if bits_per_word value is invalid.
Type:	int

extra_flags¶

Get or set the spidev extra flags. Extra flags are bitwise-ORed with the SPI mode.

Raises:	`TypeError` – if extra_flags type is not int. `ValueError` – if extra_flags value is invalid.
Type:	int

Serial¶

class mpio.Serial(devpath, baudrate, databits=8, parity='none', stopbits=1, xonxoff=False, rtscts=False)¶

Bases: object

Serial object that opens the tty device at the specified path with the specified baudrate, and the defaults of 8 data bits, no parity, 1 stop bit, no software flow control (xonxoff), and no hardware flow control (rtscts).

This can be used for simple bi-directional serial communication with connected devices.

See also

For an alternate package for interfacing with serial ports, see pySerial.

Parameters:	devpath (str) – tty device path. baudrate (int) – baudrate. databits (int) – data bits, can be 5, 6, 7, 8. parity (str) – parity, can be “none”, “even”, “odd”. stopbits (int) – stop bits, can be 1 or 2. xonxoff (bool) – software flow control. rtscts (bool) – hardware flow control.
Returns:	Serial object.
Return type:	Serial
Raises:	`TypeError` – if devpath, baudrate, databits, parity, stopbits, xonxoff, or rtscts types are invalid. `ValueError` – if baudrate, databits, parity, or stopbits values are invalid.

read(length, timeout=None)¶

Read up to length number of bytes from the serial port with an optional timeout.

timeout can be positive for a timeout in seconds, 0 for a non-blocking read, or negative or None for a blocking read that will block until length number of bytes are read. Default is a blocking read.

For a non-blocking or timeout-bound read, read() may return data whose length is less than or equal to the requested length.

Parameters:	length (int) – length in bytes. timeout (int, float, None) – timeout duration in seconds.
Returns:	data read.
Return type:	bytes

write(data)¶

Write data to the serial port and return the number of bytes written.

Parameters:	data (bytes, bytearray, list) – a byte array or list of 8-bit integers to write.
Returns:	number of bytes written.
Return type:	int
Raises:	`TypeError` – if data type is invalid. `ValueError` – if data is not valid bytes.

poll(timeout=None)¶

Poll for data available for reading from the serial port.

timeout can be positive for a timeout in seconds, 0 for a non-blocking poll, or negative or None for a blocking poll. Default is a blocking poll.

Parameters:	timeout (int, float, None) – timeout duration in seconds.
Returns:	`True` if data is available for reading from the serial port, `False` if not.
Return type:	bool

flush()¶: Flush the write buffer of the serial port, blocking until all bytes are written.

input_waiting()¶

Query the number of bytes waiting to be read from the serial port.

Returns:	number of bytes waiting to be read.
Return type:	int

output_waiting()¶

Query the number of bytes waiting to be written to the serial port.

Returns:	number of bytes waiting to be written.
Return type:	int

close()¶: Close the tty device.

fd¶

File descriptor of the underlying file.

Type:	int

devpath¶

Get the device path of the underlying tty device.

Type:	str

baudrate¶

Get or set the baudrate.

Raises:	`TypeError` – if baudrate type is not int. `ValueError` – if baudrate value is not supported.
Type:	int

databits¶

Get or set the data bits. Can be 5, 6, 7, 8.

Raises:	`TypeError` – if databits type is not int. `ValueError` – if databits value is invalid.
Type:	int

parity¶

Get or set the parity. Can be “none”, “even”, “odd”.

Raises:	`TypeError` – if parity type is not str. `ValueError` – if parity value is invalid.
Type:	str

stopbits¶

Get or set the stop bits. Can be 1 or 2.

Raises:	`TypeError` – if stopbits type is not int. `ValueError` – if stopbits value is invalid.
Type:	int

xonxoff¶

Get or set software flow control.

Raises:	`TypeError` – if xonxoff type is not bool.
Type:	bool

rtscts¶

Get or set hardware flow control.

Raises:	`TypeError` – if rtscts type is not bool.
Type:	bool

Utils¶

utils module

This module provides miscellaneous functionality both used internally and available for use externally.

mpio.utils.writestr(f, value)¶: Write a value as a str to a file descriptor or file handle.

mpio.utils.writestr_all(path, value)¶: Write a value as a str to a file path.

mpio.utils.readstr(f, maxsize=1024)¶: Read a str from a file descriptor or file handle.

mpio.utils.readstr_all(path)¶: Read a str from a file path.

mpio.utils.cpu()¶

Returns unique string identifying the current CPU.

Returns:	str

mpio.utils.board()¶

Returns a unique string identifying the current board.

Returns:	str

mpio.utils.get_trailing_number(string)¶

Returns the trailing number from a string.

Returns:	Returns int if found, `None` otherwise.
Return type:	int, None

Global¶

mpio module