luma.core.interface.serial

Encapsulates sending commands and data over a serial interface, whether that is I²C, SPI or bit-banging GPIO.

class luma.core.interface.serial.bitbang(gpio=None, transfer_size=4096, reset_hold_time=0, reset_release_time=0, **kwargs)

Bases: object

Wraps an SPI (Serial Peripheral Interface) bus to provide data() and command() methods. This is a software implementation and is thus a lot slower than the default SPI interface. Don’t use this class directly unless there is a good reason!

Parameters:

• gpio – GPIO interface (must be compatible with RPi.GPIO). For slaves that don’t need reset or D/C functionality, supply a noop implementation instead.

• transfer_size (int) – Max bytes to transfer in one go. Some implementations only support maximum of 64 or 128 bytes, whereas RPi/py-spidev supports 4096 (default).

• reset_hold_time (float) – The number of seconds to hold reset active. Some devices may require a duration of 100ms or more to fully reset the display (default: 0)

• reset_release_time (float) – The number of seconds to delay afer reset. Some devices may require a duration of 150ms or more after reset was triggered before the device can accept the initialization sequence (default: 0)

• SCLK (int) – The GPIO pin to connect the SPI clock to.

• SDA (int) – The GPIO pin to connect the SPI data (MOSI) line to.

• CE (int) – The GPIO pin to connect the SPI chip enable (CE) line to.

• DC (int) – The GPIO pin to connect data/command select (DC) to.

• RST (int) – The GPIO pin to connect reset (RES / RST) to.

cleanup()

Clean up GPIO resources if managed.

command(*cmd)

Sends a command or sequence of commands through to the SPI device.

Parameters:

cmd (int) – A spread of commands.

data(data)

Sends a data byte or sequence of data bytes through to the SPI device. If the data is more than transfer_size bytes, it is sent in chunks.

Parameters:

data (list, bytearray) – A data sequence.

luma.core.interface.serial.ftdi_i2c(device='ftdi://::/1', address=60)

Bridges an I²C (Inter-Integrated Circuit) interface over an FTDI USB device to provide data() and command() methods.

Parameters:

• device (string) – A URI describing the location of the FTDI device. If None is supplied (default), ftdi://::/1 is used. See pyftdi for further details of the naming scheme used.

• address (int) – I²C address, default: 0x3C.

Raises:

luma.core.error.DeviceAddressError – I2C device address is invalid.

New in version 1.9.0.

luma.core.interface.serial.ftdi_spi(device='ftdi://::/1', bus_speed_hz=12000000, gpio_CS=3, gpio_DC=5, gpio_RST=6, reset_hold_time=0, reset_release_time=0)

Bridges an SPI (Serial Peripheral Interface) bus over an FTDI USB device to provide data() and command() methods.

Parameters:

• device (string) –

  A URI describing the location of the FTDI device. If None is supplied (default), ftdi://::/1 is used. See pyftdi for further details of the naming scheme used.

• bus_speed_hz (int) – SPI bus speed, defaults to 12MHz.

• gpio_CS (int) – The ADx pin to connect chip select (CS) to (defaults to 3).

• gpio_DC (int) – The ADx pin to connect data/command select (DC) to (defaults to 5).

• gpio_RST (int :param reset_hold_time: The number of seconds to hold reset active. Some devices may require a duration of 100ms or more to fully reset the display (default: 0)) – The ADx pin to connect reset (RES / RST) to (defaults to 6).

• reset_release_time (float) – The number of seconds to delay afer reset. Some devices may require a duration of 150ms or more after reset was triggered before the device can accept the initialization sequence (default: 0)

New in version 1.9.0.

class luma.core.interface.serial.gpio_cs_spi(*args, **kwargs)

Bases: spi

Allows the Chip Select to be used with any GPIO pin.

The gpio pin to use is defined during instantiation with the keyword argument gpio_CS.

Parameters:

gpio_CS (int) – The GPIO pin to connect chip select (CS / CE) to (defaults to None).

cleanup()

Close pin if it was set up.

class luma.core.interface.serial.i2c(bus=None, port=1, address=60)

Bases: object

Wrap an I²C (Inter-Integrated Circuit) interface to provide data() and command() methods.

Parameters:

• bus – A smbus implementation, if None is supplied (default), smbus2 is used

• port (int) – I²C port number, usually 0 or 1 (default).

• address (int) – I²C address, default: 0x3C.

Raises:

• luma.core.error.DeviceAddressError – I2C device address is invalid.

• luma.core.error.DeviceNotFoundError – I2C device could not be found.

• luma.core.error.DevicePermissionError – Permission to access I2C device denied.

Note

1. Only one of bus OR port arguments should be supplied; if both are, then bus takes precedence.

2. If bus is provided, there is an implicit expectation that it has already been opened.

cleanup()

Clean up I²C resources

command(*cmd)

Sends a command or sequence of commands through to the I²C address - maximum allowed is 32 bytes in one go.

Parameters:

cmd (int) – A spread of commands.

Raises:

luma.core.error.DeviceNotFoundError – I2C device could not be found.

data(data)

Sends a data byte or sequence of data bytes to the I²C address. If the bus is in managed mode backed by smbus2, the i2c_rdwr method will be used to avoid having to send in chunks. For SMBus devices the maximum allowed in one transaction is 32 bytes, so if data is larger than this, it is sent in chunks.

Parameters:

data (list, bytearray) – A data sequence.

class luma.core.interface.serial.noop

Bases: object

Does nothing, used for pseudo-devices / emulators / anything really.

class luma.core.interface.serial.pcf8574(pulse_time=4.9999999999999996e-05, backlight_enabled=True, *args, **kwargs)

Bases: i2c

I²C interface to provide data() and command() methods for a device using a pcf8574 backpack.

Parameters:

• bus –

  A smbus implementation, if None is supplied (default), smbus2 is used.

• port (int) – I²C port number, usually 0 or 1 (default).

• address (int) – I²C address, default: 0x3C.

• pulse_time (float) – length of time in seconds that the enable line should be held high during a data or command transfer (default: 50μs)

• backlight_enabled (bool) – Determines whether to activate the display’s backlight

• RS (int) – where register/select is connected to the backpack (default: 0)

• E (int) – where enable pin is connected to the backpack (default: 2)

• PINS (list[int]) – The PCF8574 pins that form the data bus in LSD to MSD order

• BACKLIGHT (int) – Pin number of the pcf8574 (counting from zero) that the backlight is controlled from (default: 3)

• COMMAND (str) – determines whether RS high sets device to expect a command byte or a data byte. Must be either high (default) or low

Raises:

• luma.core.error.DeviceAddressError – I2C device address is invalid.

• luma.core.error.DeviceNotFoundError – I2C device could not be found.

• luma.core.error.DevicePermissionError – Permission to access I2C device denied.

Note

1. Only one of bus OR port arguments should be supplied; if both are, then bus takes precedence.

2. If bus is provided, there is an implicit expectation that it has already been opened.

3. Default wiring:

• RS - Register Select

• E - Enable

• RW - Read/Write (note: unused by this driver)

• D4-D7 - The upper data pins

Device	RS	RW	E	D4	D5	D6	D7	BACKLIGHT
Display	4	5	6	11	12	13	14
Backpack	P0	P1	P2	P4	P5	P6	P7	P3

If your PCF8574 is wired up differently to this you will need to provide the correct values for the RS, E, COMMAND, BACKLIGHT parameters. RS, E and BACKLIGHT are set to the pin numbers of the backpack pins they are connect to from P0-P7.

COMMAND is set to ‘high’ if the Register Select (RS) pin needs to be high to inform the device that a command byte is being sent or ‘low’ if RS low is used for commands.

PINS is a list of the pin positions that match where the devices data pins have been connected on the backpack (P0-P7). For many devices this will be d4->P4, d5->P5, d6->P6, and d7->P7 ([4, 5, 6, 7]) which is the default.

Example:

If your data lines D4-D7 are connected to the PCF8574s pins P0-P3 with the RS pin connected to P4, the enable pin to P5, the backlight pin connected to P7, and the RS value to indicate command is low, your initialization would look something like:

pcf8574(port=1, address=0x27, PINS=[0, 1, 2, 3], RS=4, E=5, COMMAND='low', BACKLIGHT=7)

Explanation: PINS are set to [0, 1, 2, 3] which assigns P0 to D4, P1 to D5, P2 to D6, and P3 to D7. RS is set to 4 to associate with P4. Similarly E is set to 5 to associate E with P5. BACKLIGHT set to 7 connects it to pin P7 of the backpack. COMMAND is set to low so that RS will be set to low when a command is sent and high when data is sent.

New in version 1.15.0.

command(*cmd)

Sends a command or sequence of commands through to the I²C address - maximum allowed is 32 bytes in one go.

Parameters:

cmd (int) – A spread of commands in high_bits, low_bits order.

Raises:

luma.core.error.DeviceNotFoundError – I2C device could not be found.

IMPORTANT: the PCF8574 only supports four bit transfers. It is the devices responsibility to break each byte sent into a high bit and a low bit transfer.

Example:

To set an HD44780s cursor to the beginning of the first line requires sending 0b10000000 (0x80). This is 0b1000 (0x08) at the high side of the byte and 0b0000 (0x00) on the low side of the byte.

For example, to send this using the pcf8574 interface:

d = pcf8574(bus=1, address=0x27)
d.command([0x08, 0x00])

data(data)

Sends a data byte or sequence of data bytes to the I²C address.

Parameters:

data (list, bytearray) – A data sequence.

IMPORTANT: the PCF8574 only supports four bit transfers. It is the devices responsibility to break each byte sent into a high bit and a low bit transfer.

Example:

To send an ascii ‘A’ (0x41) to the display you need to send binary 01000001. This is 0100 (0x40) at the high side of the byte and 0001 (0x01) on the low side of the byte.

For example, to send this using the pcf8574 interface:

d = pcf8574(bus=1, address=0x27)
d.command([0x04, 0x01])

class luma.core.interface.serial.spi(spi=None, gpio=None, port=0, device=0, bus_speed_hz=8000000, transfer_size=4096, gpio_DC=24, gpio_RST=25, spi_mode=None, reset_hold_time=0, reset_release_time=0, **kwargs)

Bases: bitbang

Wraps an SPI (Serial Peripheral Interface) bus to provide data() and command() methods.

Parameters:

• spi – SPI implementation (must be compatible with spidev)

• gpio – GPIO interface (must be compatible with RPi.GPIO). For slaves that don’t need reset or D/C functionality, supply a noop implementation instead.

• port (int) – SPI port, usually 0 (default) or 1.

• device (int) – SPI device, usually 0 (default) or 1.

• bus_speed_hz (int) – SPI bus speed, defaults to 8MHz.

• transfer_size (int) – Maximum amount of bytes to transfer in one go. Some implementations only support a maximum of 64 or 128 bytes, whereas RPi/py-spidev supports 4096 (default).

• gpio_DC (int) – The GPIO pin to connect data/command select (DC) to (defaults to 24).

• gpio_RST (int) – The GPIO pin to connect reset (RES / RST) to (defaults to 25).

• spi_mode (int) – SPI mode as two bit pattern of clock polarity and phase [CPOL|CPHA], 0-3 (default:None)

• reset_hold_time (float) – The number of seconds to hold reset active. Some devices may require a duration of 100ms or more to fully reset the display (default: 0)

• reset_release_time (float) – The number of seconds to delay afer reset. Some devices may require a duration of 150ms or more after reset was triggered before the device can accept the initialization sequence (default: 0)

Raises:

• luma.core.error.DeviceNotFoundError – SPI device could not be found.

• luma.core.error.UnsupportedPlatform – GPIO access not available.

cleanup()

Clean up SPI & GPIO resources.

luma.core.interface.parallel

Encapsulates sending commands and data over a parallel-bus interface.

class luma.core.interface.parallel.bitbang_6800(gpio=None, pulse_time=4.9999999999999996e-05, **kwargs)

Bases: object

Implements a 6800 style parallel-bus interface that provides data() and command() methods. The default pin assignments provided are from Adafruit.

Parameters:

• gpio – GPIO interface (must be compatible with RPi.GPIO)

• pulse_time (float) – length of time in seconds that the enable line should be held high during a data or command transfer

• RS (int) – The GPIO pin register select (RS) line (low for command, high for data). Default: 22

• E (int) – The GPIO pin to connect the enable (E) line to. Default: 17

• PINS (list[int]) – The GPIO pins that form the data bus (a list of 4 or 8 pins depending upon implementation ordered from LSD to MSD). Default: [25, 24, 23, 18]

New in version 1.16.2.

cleanup()

Clean up GPIO resources.

command(*cmd)

Sends a command or sequence of commands through the bus.

If the bus is in 4-bit mode, only the lowest 4 bits of the data value will be sent.

This means that the device needs to send high and low bits separately if the device is operating using a 4-bit bus; to send a 0x32 in 4-bit mode the device would use: command(0x03, 0x02)

Parameters:

cmd (int) – A spread of commands.

data(data)

Sends a data byte or sequence of data bytes through to the bus.

If the bus is in 4-bit mode, only the lowest 4 bits of the data value will be sent.

This means that the device needs to send high and low bits separately if the device is operating using a 4-bit bus; to send a 0x32 in 4-bit mode the device would use: data([0x03, 0x02])

Parameters:

data (list, bytearray) – A data sequence.