public interface SPIDevice extends Device
SPIDevice interface provides methods for transmitting and receiving data to/from an SPI slave device.
An SPI slave device may be identified by the numeric ID and by the name (if any defined) that correspond to its
registered configuration. An SPIDevice instance can be opened by a call to
DeviceManager.open(config,...)
On an SPI bus, data is transferred between the SPI master device and an SPI slave device in full duplex. That is, data is transmitted by the SPI master to the SPI slave device at the same time data is received from the SPI slave device by the SPI master.
To perform such a bidirectional exchange of data with an SPI slave device, an application may use one of the
writeAndRead methods.
When an application only wants to send data to or receive data from an SPI slave device, it may use the
write or the read method, respectively. When writing only, the
data received from the SPI slave device will be ignored/discarded. When reading only, dummy data will be sent to the
slave.
A data exchange consists of words of a certain length which may vary from SPI
slave device to SPI slave device.
Words in the sending and receiving byte buffers are not packed (bit-wise) and
must be byte-aligned; bytes are copied out or in, respectively, from/to these
buffers according to their byte orders and the bits are shifted out or
in, respectively, according to the bit ordering configured for the device
(see
SPIDeviceConfig.getBitOrdering).
If a word's length is not a multiple of 8
(the byte length in bits) then the most significant bits will be undefined when receiving or unused when sending. If
the designated portion of a sending or receiving byte buffer cannot contain a (positive) integral number of words
then an InvalidWordLengthException will be thrown. For example, if the word length is 16bits and the
designated portion of buffer is only 1-byte long or is 3-byte long an InvalidWordLengthException will be
thrown.
Assuming a word length w, the length l of the designated portion of the sending or receiving byte
buffer must be such that:
((l % (((w - 1) / 8) + 1)) == 0)
Since the SPI master device controls the serial transmission clock read and write operations are never blocked nor delayed by
unresponsive slave devices. Not though that a read or write operation may be blocked if another read or write operation
is concurrently being performed on the same SPIDevice instance.
When the data exchange is over, an application should call the SPIDevice.close method to close the
SPI slave device. Any further attempt to transmit/write or receive/read to/from an SPI slave device which has been
closed will result in a ClosedDeviceException been thrown.
SPIDevice instance may additionally implement
the Transactional interface to indicate that it supports SPI transactions. In such a case the Transactional.begin
and Transactional.end methods may be used to demarcate the beginning and the end of an SPI transaction.
This typically results in the SPI slave's Select line (SS) remaining asserted during the whole sequence of read and write operations performed within the demarcated
transaction. It is the responsibility of the application to appropriately control the timing between a call to the begin method which
may assert the Chip Select (depending on the configuration, see SPIDeviceConfig.CS_NOT_CONTROLLED) and
subsequent calls to the read, write and writeAndRead methods.
An application can alternatively perform a sequence of reads and/or writes - from/to one or several slaves, that
are guaranteed to be performed as a single transaction using an SPICompositeMessage object.
SPICompositeMessage,
InvalidWordLengthException,
ClosedDeviceExceptionBIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN| Modifier and Type | Method and Description |
|---|---|
SPICompositeMessage |
createCompositeMessage()
Creates a new
SPICompositeMessage instance targeting this slave
device. |
int |
getWordLength()
Gets the transfer word length in bits supported by this slave device.
|
int |
read()
Reads one data word of up to 32 bits from this slave device.
|
int |
read(ByteBuffer dst)
Reads a sequence of bytes from this slave device into the given buffer.
|
int |
read(int skip,
ByteBuffer dst)
Reads a sequence of bytes from this device into the given buffer, skipping the first
skip bytes read. |
int |
write(ByteBuffer src)
Writes a sequence of bytes to this slave device from the given buffer.
|
void |
write(int txData)
Writes one data word of up to 32 bits to this slave device.
|
int |
writeAndRead(ByteBuffer src,
ByteBuffer dst)
Exchanges (transmits and receives) data with this slave device.
|
int |
writeAndRead(ByteBuffer src,
int skip,
ByteBuffer dst)
Exchanges (transmits and receives) data with this slave device skipping the specified number of bytes received.
|
int |
writeAndRead(int txData)
Exchanges (transmits and receives) one data word of up to 32 bits with this slave device.
|
SPICompositeMessage createCompositeMessage()
SPICompositeMessage instance targeting this slave
device.SPICompositeMessage instance.int getWordLength()
throws IOException,
UnavailableDeviceException,
ClosedDeviceException
If the length of data to be exchanged belies a slave's word length an InvalidWordLengthException will be
thrown.
IOException - if some other I/O error occurs.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.ClosedDeviceException - if the device has been closed.int read()
throws IOException,
UnavailableDeviceException,
ClosedDeviceException
This method may be invoked at any time. If another thread has already initiated a read or write operation upon this slave device, however, then an invocation of this method will block until the first operation is complete.
IOException - if some other I/O error occurs.InvalidWordLengthException - if the number of bytes to receive belies word length; that is this slave's word length is bigger than
32 bits.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.ClosedDeviceException - if the device has been closed.int read(ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
Dummy data will be sent to this slave device by the platform.
An attempt is made to read up to r bytes from the device, where r is the number
of bytes remaining in the buffer, that is, dst.remaining(), at the moment this method
is invoked.
Suppose that a byte sequence of length n is read, where 0 <= n <= r.
This byte sequence will be transferred into the buffer so that the first byte in the sequence
is at index p and the last byte is at index p + n - 1, where p
is the buffer's position at the moment this method is invoked. Upon return the buffer's
position will be equal to p + n; its limit will not have changed.
A read operation will block until the requested r bytes are read.
This method may be invoked at any time. If another thread has already initiated a read or write operation upon this slave device, however, then an invocation of this method will block until the first operation is complete.
dst - the buffer into which bytes are to be transferreddst, possibly zero.NullPointerException - if dst is null.InvalidWordLengthException - if the number of bytes to receive belies word length.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.UnsupportedByteOrderException - if the byte ordering of the provided buffer is not supported (see Device Byte Order).ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.int read(int skip,
ByteBuffer dst)
throws IOException,
UnavailableDeviceException,
UnsupportedByteOrderException,
ClosedDeviceException
skip bytes read.
Dummy data will be sent to this slave device by the platform.
Apart from skipping the first skip bytes, this method behaves identically to
read(org.joshvm.util.ByteBuffer).
skip - the number of read bytes that must be ignored/skipped before filling in the dst buffer.dst - the buffer into which bytes are to be transferreddst, possibly zero.NullPointerException - if dst is null.IllegalArgumentException - if skip is negative.InvalidWordLengthException - if the total number of bytes to receive belies word length.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.UnsupportedByteOrderException - if the byte ordering of the provided buffer is not supported (see Device Byte Order).ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.int write(ByteBuffer src) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
An attempt is made to write up to r bytes to the device, where r is the number
of bytes remaining in the buffer, that is, src.remaining(), at the moment this method
is invoked.
Suppose that a byte sequence of length n is written, where 0 <= n <= r.
This byte sequence will be transferred from the buffer starting at index p, where
p is the buffer's position at the moment this method is invoked; the index of the last
byte written will be p + n - 1. Upon return the buffer's position will be
equal to p + n; its limit will not have changed.
A write operation will return only after writing all of the r requested bytes.
This method may be invoked at any time. If another thread has already initiated a read or write operation upon this slave device, however, then an invocation of this method will block until the first operation is complete.
src - the buffer from which bytes are to be retrieved.src, possibly zero.InvalidWordLengthException - if the number of bytes to send belies word length.NullPointerException - if src is null.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.UnsupportedByteOrderException - if the byte ordering of the provided buffer is not supported (see Device Byte Order).ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.void write(int txData)
throws IOException,
UnavailableDeviceException,
ClosedDeviceException
This method may be invoked at any time. If another thread has already initiated a read or write operation upon this slave device, however, then an invocation of this method will block until the first operation is complete.
txData - the data word to be written.IOException - if an I/O error occurred.InvalidWordLengthException - if the number of bytes to send belies word length; that is this slave's word length is bigger than 32
bits.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.ClosedDeviceException - if the device has been closed.int writeAndRead(ByteBuffer src, ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
The designated portions of the sending and receiving byte buffers may not have the same length. When sending more than is being received the extra received bytes are ignored/discarded. Conversely, when sending less than is being received extra dummy data will be sent.
This method behaves as a combined write(org.joshvm.util.ByteBuffer) and
read(org.joshvm.util.ByteBuffer).
src - the buffer from which bytes are to be retrieved.dst - the buffer into which bytes are to be transferred.dst, possibly zero.NullPointerException - if src or dst is null.InvalidWordLengthException - if the number of bytes to receive or send belies word length.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.UnsupportedByteOrderException - if the byte ordering of the any of the provided buffers is not supported (see Device Byte Order).ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.int writeAndRead(ByteBuffer src, int skip, ByteBuffer dst) throws IOException, UnavailableDeviceException, UnsupportedByteOrderException, ClosedDeviceException
The designated portions of the sending and receiving byte buffers may not have the same length. When sending more than is being received the extra received bytes are ignored/discarded. Conversely, when sending less than is being received extra dummy data will be sent.
This method behaves as a combined write(org.joshvm.util.ByteBuffer) and
read(org.joshvm.util.ByteBuffer).
src - the buffer from which bytes are to be retrieved.skip - the number of received bytes that must be ignored/skipped before filling in the dst buffer.dst - the buffer into which bytes are to be transferred.dst, possibly zero.NullPointerException - if src or dst is null.IllegalArgumentException - if skip is negative.InvalidWordLengthException - if the total number of bytes to receive or send belies word length.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.UnsupportedByteOrderException - if the byte ordering of the any of the provided buffers is not supported (see Device Byte Order).ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.int writeAndRead(int txData)
throws IOException,
UnavailableDeviceException,
ClosedDeviceException
This method may be invoked at any time. If another thread has already initiated a read or write operation upon this slave device, however, then an invocation of this method will block until the first operation is complete.
txData - the word to send.IOException - if some other I/O error occurs.InvalidWordLengthException - if the numbers of bytes to send or to receive bely word length; that is this slave's word length is
bigger than 32 bits.UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.ClosedDeviceException - if the device has been closed.