Returns as bit mask with bit_num set.

Parameters:bit_num (int) – The bit number.
Returns:int – the bit mask
>>> bin(pifacecommon.core.get_bit_mask(0))
>>> pifacecommon.core.get_bit_mask(1)
>>> bin(pifacecommon.core.get_bit_mask(3))

Returns the lowest bit num from a given bit pattern. Returns None if no bits set.

Parameters:bit_pattern (int) – The bit pattern.
Returns:int – the bit number
Returns:None – no bits set
>>> pifacecommon.core.get_bit_num(0)
>>> pifacecommon.core.get_bit_num(0b1)
>>> pifacecommon.core.get_bit_num(0b11000)

Sleeps for the given number of microseconds.

Parameters:microseconds (int) – Number of microseconds to sleep for.


class pifacecommon.spi.SPIDevice(bus=0, chip_select=0, spi_callback=None)

An SPI Device at /dev/spi<bus>.<chip_select>.


Sends bytes via the SPI bus.

Parameters:bytes_to_send (bytes) – The bytes to send on the SPI device.
Returns:bytes – returned bytes from SPI device


class pifacecommon.interrupts.EventQueue(pin_function_maps)

Stores events in a queue.


Adds events to the queue. Will ignore events that occur before the settle time for that pin/direction. Such events are assumed to be bouncing.

class pifacecommon.interrupts.FunctionMap(callback, settle_time=None)

Maps something to a callback function. (This is an abstract class, you must implement a SomethingFunctionMap).

class pifacecommon.interrupts.GPIOInterruptDevice

A device that interrupts using the GPIO pins.


Disables gpio interrupts.


Enables GPIO interrupts.

class pifacecommon.interrupts.InterruptEvent(interrupt_flag, interrupt_capture, chip, timestamp)

An interrupt event containting the interrupt flag and capture register values, the chip object from which the interrupt occured and a timestamp.

class pifacecommon.interrupts.PinFunctionMap(pin_num, direction, callback, settle_time)

Maps an IO pin and a direction to callback function.

class pifacecommon.interrupts.PortEventListener(port, chip, return_after_kbdint=True)

Listens for port events and calls the registered functions.

>>> def print_flag(event):
...     print(event.interrupt_flag)
>>> port = pifacecommon.mcp23s17.GPIOA
>>> listener = pifacecommon.interrupts.PortEventListener(port)
>>> listener.register(0, pifacecommon.interrupts.IODIR_ON, print_flag)
>>> listener.activate()

When activated the PortEventListener will run callbacks associated with pins/directions.


When deactivated the PortEventListener will not run anything.

deregister(pin_num=None, direction=None)

De-registers callback functions

  • pin_num (int) – The pin number. If None then all functions are de-registered
  • direction – The event direction. If None then all functions for the given pin are de-registered

:type direction:int

register(pin_num, direction, callback, settle_time=0.02)

Registers a pin number and direction to a callback function.

  • pin_num (int) – The pin pin number.
  • direction (int) – The event direction (use: IODIR_ON/IODIR_OFF/IODIR_BOTH)
  • callback (function) – The function to run when event is detected.
  • settle_time (int) – Time within which subsequent events are ignored.

Bring the interrupt pin on the GPIO into Linux userspace.


Remove the GPIO interrupt pin from Linux userspace.

pifacecommon.interrupts.handle_events(function_maps, event_queue, event_matches_function_map, terminate_signal)

Waits for events on the event queue and calls the registered functions.

  • function_maps (list) – A list of classes that have inheritted from FunctionMaps describing what to do with events.
  • event_queue (multiprocessing.Queue) – A queue to put events on.
  • event_matches_function_map (function) – A function that determines if the given event and FunctionMap match.
  • terminate_signal – The signal that, when placed on the event queue, causes this function to exit.

Set the interrupt edge on the userspace GPIO pin.

Parameters:edge (string) – The interrupt edge (‘none’, ‘falling’, ‘rising’).

Wait until a file exists.

Parameters:filename (string) – The name of the file to wait for.
pifacecommon.interrupts.watch_port_events(port, chip, pin_function_maps, event_queue, return_after_kbdint=False)

Waits for a port event. When a port event occurs it is placed onto the event queue.

  • port (int) – The port we are waiting for interrupts on (GPIOA/GPIOB).
  • chip (pifacecommon.mcp23s17.MCP23S17) – The chip we are waiting for interrupts on.
  • pin_function_maps (list) – A list of classes that have inheritted from FunctionMaps describing what to do with events.
  • event_queue (multiprocessing.Queue) – A queue to put events on.


Consult the datasheet for more information.

class pifacecommon.mcp23s17.MCP23S17(hardware_addr=0, bus=0, chip_select=0)

Microchip’s MCP23S17: A 16-Bit I/O Expander with Serial Interface.

Attribute:iodira/iodirb – Controls the direction of the data I/O.
Attribute:ipola/ipolb –This register allows the user to configure the polarity on the corresponding GPIO port bits.
Attribute:gpintena/gpintenb – The GPINTEN register controls the interrupt-onchange feature for each pin.
Attribute:defvala/defvalb –The default comparison value is configured in the DEFVAL register.
Attribute:intcona/intconb –The INTCON register controls how the associated pin value is compared for the interrupt-on-change feature.
Attribute:iocon –The IOCON register contains several bits for configuring the device.
Attribute:gppua/gppub –The GPPU register controls the pull-up resistors for the port pins.
Attribute:intfa/intfb –The INTF register reflects the interrupt condition on the port pins of any pin that is enabled for interrupts via the GPINTEN register.
Attribute:intcapa/intcapb – The INTCAP register captures the GPIO port value at the time the interrupt occurred.
Attribute:gpioa/gpiob – The GPIO register reflects the value on the port.
Attribute:olata/olatb – The OLAT register provides access to the output latches.

Clears the interrupt flags by ‘read’ing the capture register.


Returns the value of the address specified.

Parameters:address (int) – The address to read from.
read_bit(bit_num, address)

Returns the bit specified from the address.

  • bit_num (int) – The bit number to read from.
  • address (int) – The address to read from.

int – the bit value from the address

write(data, address)

Writes data to the address specified.

  • data (int) – The data to write.
  • address (int) – The address to write to.
write_bit(value, bit_num, address)

Writes the value given to the bit in the address specified.

  • value (int) – The value to write.
  • bit_num (int) – The bit number to write to.
  • address (int) – The address to write to.
class pifacecommon.mcp23s17.MCP23S17Register(address, chip)

An 8-bit register inside an MCP23S17.

class pifacecommon.mcp23s17.MCP23S17RegisterBase(address, chip)

Base class for objects on an 8-bit register inside an MCP23S17.

class pifacecommon.mcp23s17.MCP23S17RegisterBit(bit_num, address, chip)

A bit inside register inside an MCP23S17.

class pifacecommon.mcp23s17.MCP23S17RegisterBitNeg(bit_num, address, chip)

A negated bit inside register inside an MCP23S17.

class pifacecommon.mcp23s17.MCP23S17RegisterNeg(address, chip)

An negated 8-bit register inside an MCP23S17.

class pifacecommon.mcp23s17.MCP23S17RegisterNibble(nibble, address, chip)

An 4-bit nibble inside a register inside an MCP23S17.

class pifacecommon.mcp23s17.MCP23S17RegisterNibbleNeg(nibble, address, chip)

A negated 4-bit nibble inside a register inside an MCP23S17.