net.freeutils.scrollphat

Class Device

java.lang.Object

net.freeutils.scrollphat.Device

All Implemented Interfaces:

Closeable, AutoCloseable

Direct Known Subclasses:

JNADevDevice, MockDevice, Pi4JDevice

public abstract class Device
extends Object
implements Closeable

Provides access to the raw functionality of ISSI's IS31FL3730 matrix LED driver chip.

The device must be opened and configured before being used (the init() method does both with default values).

The device must be closed when done, in order to clear the display and release all resources. The method can be called to enable a shutdown hook that will close the device automatically when the JVM exits, which is convenient in most simple use cases.

The LED matrix data is written via the setDisplay(int, int) methods. Data is expressed as a single byte per column, where each bit represents the state of a single led on that column. Columns are indexed from left to right, and the rows within a column are indexed from top (lowest bit) to bottom (highest bit).

The written matrix data is stored by the device in temporary registers, and becomes visible only when the update() method is invoked to apply the changes.

The LED brightness can be set as a value in the range 0 (off) to 128 (brightest). The brightness setting applies to the entire matrix and cannot be set for each LED individually.

This class is not thread-safe, and should only be accessed by one thread at a time.

See Also:

IS31FL3730 Datasheet

Field Summary

Fields

Modifier and Type	Field and Description
static int	ADDR_GND
static int	ADDR_SCL
static int	ADDR_SDA
static int	ADDR_VCC
static byte	CONFIG_AUDIO_INPUT
static byte	CONFIG_DISPLAY_MATRIX_1
static byte	CONFIG_DISPLAY_MATRIX_1_AND_2
static byte	CONFIG_DISPLAY_MATRIX_2
static byte	CONFIG_MATRIX_5X11
static byte	CONFIG_MATRIX_6X10
static byte	CONFIG_MATRIX_7X9
static byte	CONFIG_MATRIX_8X8
static byte	CONFIG_SOFTWARE_SHUTDOWN
protected int	errors
protected int	height
static byte	REG_BRIGHTNESS_CONFIG
static byte	REG_BRIGHTNESS_PWM
static byte	REG_CONFIG
static byte	REG_MATRIX1_DATA_START
static byte	REG_MATRIX2_DATA_START
static byte	REG_RESET
static byte	REG_UPDATE
protected Thread	shutdownHook
protected int	throwErrorCount
protected int	warnErrorCount
protected int	width

Constructor Summary

Constructors

Constructor and Description
Device()

Method Summary

Modifier and Type	Method and Description
void	close() Closes the I2C bus and device.
protected abstract void	closeImpl() Closes the I2C bus and device.
Device	closeOnShutdown(boolean enable) Specifies whether to set a system shutdown hook to close this device when the JVM exits.
Device	configure(int config) Configures the device.
void	displayTestPatterns() Displays test patterns.
int	getHeight() Returns the configured device height.
int	getWidth() Returns the configured device width.
protected void	handleError(IOException ioe) Handles errors that occur while writing data to the device.
Device	init() Initializes the device.
static void	main(String[] args) The main command-line utility entry point.
static Device	newInstance() Returns a new Device instance.
static Device	newInstance(String impl) Returns a new Device instance using the given implementation.
Device	open(int address) Opens the connection to I2C bus number 1 and to the device at the given address.
Device	open(int busNumber, int address) Opens the connection to the I2C bus and to the device at the given address.
protected abstract Device	openImpl(int busNumber, int address) Opens the connection to the I2C bus and to the device at the given address.
void	reset() Resets the device (by writing the reset command to it).
void	setBrightness(int value) Sets the display brightness.
void	setDisplay(byte[] columns) Sets the values of a consecutive sequence of columns, starting at the first column.
void	setDisplay(int startColumn, byte[] columns) Sets the values of a consecutive sequence of columns.
void	setDisplay(int startColumn, byte[] columns, int offset, int length) Sets the values of a consecutive sequence of columns.
void	setDisplay(int column, int value) Sets the value of the given column.
void	update() Updates the display.
void	update(byte[] columns) Writes the given display data and updates the display.
void	write(byte register, byte[] data, int offset, int length) Writes a series of bytes of data starting at the given register.
void	write(byte register, int data) Writes a single byte of data to the given register.
protected abstract void	writeImpl(byte register, byte[] data, int offset, int length) Writes a series of bytes of data starting at the given register.
protected void	writeImpl(byte register, int data) Writes a single byte of data to the given register.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ADDR_GND

public static final int ADDR_GND

See Also:

Constant Field Values

ADDR_SCL

public static final int ADDR_SCL

See Also:

Constant Field Values

ADDR_SDA

public static final int ADDR_SDA

See Also:

Constant Field Values

ADDR_VCC

public static final int ADDR_VCC

See Also:

Constant Field Values

REG_CONFIG

public static final byte REG_CONFIG

See Also:

Constant Field Values

REG_MATRIX1_DATA_START

public static final byte REG_MATRIX1_DATA_START

See Also:

Constant Field Values

REG_MATRIX2_DATA_START

public static final byte REG_MATRIX2_DATA_START

See Also:

Constant Field Values

REG_UPDATE

public static final byte REG_UPDATE

See Also:

Constant Field Values

REG_BRIGHTNESS_CONFIG

public static final byte REG_BRIGHTNESS_CONFIG

See Also:

Constant Field Values

REG_BRIGHTNESS_PWM

public static final byte REG_BRIGHTNESS_PWM

See Also:

Constant Field Values

REG_RESET

public static final byte REG_RESET

See Also:

Constant Field Values

CONFIG_MATRIX_8X8

public static final byte CONFIG_MATRIX_8X8

See Also:

Constant Field Values

CONFIG_MATRIX_7X9

public static final byte CONFIG_MATRIX_7X9

See Also:

Constant Field Values

CONFIG_MATRIX_6X10

public static final byte CONFIG_MATRIX_6X10

See Also:

Constant Field Values

CONFIG_MATRIX_5X11

public static final byte CONFIG_MATRIX_5X11

See Also:

Constant Field Values

CONFIG_AUDIO_INPUT

public static final byte CONFIG_AUDIO_INPUT

See Also:

Constant Field Values

CONFIG_DISPLAY_MATRIX_1

public static final byte CONFIG_DISPLAY_MATRIX_1

See Also:

Constant Field Values

CONFIG_DISPLAY_MATRIX_2

public static final byte CONFIG_DISPLAY_MATRIX_2

See Also:

Constant Field Values

CONFIG_DISPLAY_MATRIX_1_AND_2

public static final byte CONFIG_DISPLAY_MATRIX_1_AND_2

See Also:

Constant Field Values

CONFIG_SOFTWARE_SHUTDOWN

public static final byte CONFIG_SOFTWARE_SHUTDOWN

See Also:

Constant Field Values

errors

protected int errors

warnErrorCount

protected int warnErrorCount

throwErrorCount

protected int throwErrorCount

width

protected int width

height

protected int height

shutdownHook

protected Thread shutdownHook

Constructor Detail

Device

public Device()

Method Detail

newInstance

public static Device newInstance()

Returns a new Device instance.

The implementation name can be specified in the "scrollphat.impl" system property, and if none exists, a default is used.

Returns:

a new Device instance

Throws:

IllegalArgumentException - if the implementation name is invalid

newInstance

public static Device newInstance(String impl)

Returns a new Device instance using the given implementation.

The implementation name can be one of "pi4j", "jnadev" or "mock". If null, the implementation name is taken from the "scrollphat.impl" system property, and if none exists, a default is used.

Parameters:

impl - the implementation name

Returns:

a new Device instance

Throws:

IllegalArgumentException - if the implementation name is invalid

getWidth

public int getWidth()

Returns the configured device width.

Returns:

the configured device width

getHeight

public int getHeight()

Returns the configured device height.

Returns:

the configured device height

handleError

protected void handleError(IOException ioe)
                    throws IOException

Handles errors that occur while writing data to the device.

The error may be rethrown, swallowed, or a warning printed, depending on the error handling configuration and current accumulated error count.

Parameters:

ioe - the error that occurred

Throws:

IOException - if the error is to be propagated

open

public Device open(int address)
            throws IOException

Opens the connection to I2C bus number 1 and to the device at the given address.

Parameters:

address - the I2C device address

Returns:

this device

Throws:

IOException - if an error occurs

IllegalArgumentException - if the address is invalid

open

public Device open(int busNumber,
                   int address)
            throws IOException

Opens the connection to the I2C bus and to the device at the given address.

Parameters:

busNumber - the I2C bus number to use

address - the I2C device address

Returns:

this device

Throws:

IOException - if an error occurs

IllegalArgumentException - if the address is invalid

openImpl

protected abstract Device openImpl(int busNumber,
                                   int address)
                            throws IOException

Opens the connection to the I2C bus and to the device at the given address.

Parameters:

busNumber - the I2C bus number to use

address - the I2C device address

Returns:

this device

Throws:

IOException - if an error occurs

IllegalArgumentException - if the address is invalid

close

public void close()
           throws IOException

Closes the I2C bus and device.

This method may be called multiple times, or without a successful call to open(int) before it.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException - if an error occurs

closeImpl

protected abstract void closeImpl()
                           throws IOException

Closes the I2C bus and device.

This method may be called multiple times, or without a successful call to open(int) before it.

Throws:

IOException - if an error occurs

write

public void write(byte register,
                  int data)
           throws IOException

Writes a single byte of data to the given register.

Parameters:

register - the register to write to

data - the data to write (only the lower 8 bits are written)

Throws:

IOException - if an error occurs

writeImpl

protected void writeImpl(byte register,
                         int data)
                  throws IOException

Writes a single byte of data to the given register.

Parameters:

register - the register to write to

data - the data to write (only the lower 8 bits are written)

Throws:

IOException - if an error occurs

write

public void write(byte register,
                  byte[] data,
                  int offset,
                  int length)
           throws IOException

Writes a series of bytes of data starting at the given register. The register number is incremented by one after each written byte.

Parameters:

register - the register to write to

data - an array containing the data to write

offset - the offset within the array of the first byte to write

length - the number of bytes to write

Throws:

IOException - if an error occurs

writeImpl

protected abstract void writeImpl(byte register,
                                  byte[] data,
                                  int offset,
                                  int length)
                           throws IOException

Writes a series of bytes of data starting at the given register. The register number is incremented by one after each written byte.

Parameters:

register - the register to write to

data - an array containing the data to write

offset - the offset within the array of the first byte to write

length - the number of bytes to write

Throws:

IOException - if an error occurs

closeOnShutdown

public Device closeOnShutdown(boolean enable)

Specifies whether to set a system shutdown hook to close this device when the JVM exits.

If disabled, the caller is responsible for performing a graceful shutdown, e.g. by calling close() in a finally block.

Parameters:

enable - specifies whether to enable or disable close on shutdown

Returns:

this device

configure

public Device configure(int config)
                 throws IOException

Configures the device.

Parameters:

config - the bitmask of configuration options

Returns:

this device

Throws:

IOException - if an error occurs

init

public Device init()
            throws IOException

Initializes the device.

This is a convenience method that calls closeOnShutdown(boolean), open(int) and configure(int) with default options.

Returns:

this device

Throws:

IOException - if an error occurs

reset

public void reset()
           throws IOException

Resets the device (by writing the reset command to it).

Throws:

IOException - if an error occurs

setBrightness

public void setBrightness(int value)
                   throws IOException

Sets the display brightness.

Parameters:

value - a brightness value in the range 0-128

Throws:

IOException - if an error occurs

update

public void update()
            throws IOException

Updates the display. This method must be called after modifying the display data in order for the changes to be applied.

Throws:

IOException - if an error occurs

update

public void update(byte[] columns)
            throws IOException

Writes the given display data and updates the display.

Parameters:

columns - the consecutive column values to write

Throws:

IOException - if an error occurs

setDisplay

public void setDisplay(int column,
                       int value)
                throws IOException

Sets the value of the given column.

Parameters:

column - the column number

value - the column value

Throws:

IOException - if an error occurs

setDisplay

public void setDisplay(int startColumn,
                       byte[] columns,
                       int offset,
                       int length)
                throws IOException

Sets the values of a consecutive sequence of columns.

Parameters:

startColumn - the column to start writing at

columns - an array containing the consecutive column values to write

offset - the offset within the array of the first column's value

length - the number of consecutive column values to write

Throws:

IOException - if an error occurs

setDisplay

public void setDisplay(int startColumn,
                       byte[] columns)
                throws IOException

Sets the values of a consecutive sequence of columns.

Parameters:

startColumn - the column to start writing at

columns - the consecutive column values to write

Throws:

IOException - if an error occurs

setDisplay

public void setDisplay(byte[] columns)
                throws IOException

Sets the values of a consecutive sequence of columns, starting at the first column.

Parameters:

columns - the consecutive column values to write

Throws:

IOException - if an error occurs

displayTestPatterns

public void displayTestPatterns()
                         throws IOException,
                                InterruptedException

Displays test patterns. This functionality is implemented in software and not by the device itself, but is useful in verifying that the device is working properly.

Throws:

IOException - if an error occurs

InterruptedException - if the thread is interrupted

main

public static void main(String[] args)
                 throws IOException,
                        InterruptedException

The main command-line utility entry point.

Parameters:

args - the arguments

Throws:

IOException - if an error occurs

InterruptedException - if the thread is interrupted