public interface SPIDevice extends Peripheral<SPIDevice>, java.nio.channels.ByteChannel, Transactional, BufferAccess<java.nio.ByteBuffer>
SPIDevice
interface provides methods for transmitting and receiving data to/from an SPI slave device.
An SPI slave device may be identified by the numerical ID and by the name (if any defined) that correspond to its
registered configuration. An SPIDevice
instance can be opened by a call to one of the
PeripheralManager.open(id,...)
methods using its ID or by a call to one of the
PeripheralManager.open(name,...)
methods using its name. When an SPIDevice
instance is opened with an ad-hoc
SPIDeviceConfig
configuration (which includes its hardware addressing information) using one of the
PeripheralManager.open(config,...)
it is not
assigned any ID nor name.
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. 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. 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. SPIDevice
instance).
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.
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 ClosedPeripheralException
been thrown.BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
Modifier and Type | Method and Description |
---|---|
void |
begin()
Demarcates the beginning of an SPI transaction so that this slave's Select line (SS) will be remain asserted
during the subsequent read and write operations and until the transaction ends.
|
void |
end()
Demarcates the end of a transaction hence ending the assertion of this slave's Select line (SS).
|
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(java.nio.ByteBuffer dst)
Reads a sequence of bytes from this slave device into the given buffer.
|
int |
read(int skip,
java.nio.ByteBuffer dst)
Reads a sequence of bytes from this device into the given buffer, skipping the first
skip bytes read. |
int |
write(java.nio.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(java.nio.ByteBuffer src,
java.nio.ByteBuffer dst)
Exchanges (transmits and receives) data with this slave device.
|
int |
writeAndRead(java.nio.ByteBuffer src,
int skip,
java.nio.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.
|
close, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer
void begin() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
begin
in interface Transactional
UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.IllegalStateException
- if a transaction is already in progress.void end() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
end
in interface Transactional
UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- if some other I/O error occurs.java.lang.IllegalStateException
- if a transaction is not currently in progress.int getWordLength() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
If the length of data to be exchanged belies a slave's word length an InvalidWordLengthException
will be
thrown.
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int read() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
java.io.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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int read(java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
read
in interface java.nio.channels.ReadableByteChannel
dst
- The buffer into which bytes are to be transferred-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.InvalidWordLengthException
- if the number of bytes to receive belies word length.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursint read(int skip, java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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(java.nio.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 transferred-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If dst
is null
.InvalidWordLengthException
- if the total number of bytes to receive belies word length.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursint write(java.nio.ByteBuffer src) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
write
in interface java.nio.channels.WritableByteChannel
src
- The buffer from which bytes are to be retrievedjava.lang.NullPointerException
- If src
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursvoid write(int txData) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
txData
- the data word to be writtenjava.io.IOException
- if an I/O error occurredInvalidWordLengthException
- if the number of bytes to send belies word length; that is this slave's word length is bigger than 32
bits.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int writeAndRead(java.nio.ByteBuffer src, java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
write(java.nio.ByteBuffer)
and
read(java.nio.ByteBuffer)
.src
- The buffer from which bytes are to be retrieveddst
- The buffer into which bytes are to be transferred-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If src
or dst
is null
.InvalidWordLengthException
- if the number of bytes to receive or send belies word length.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursint writeAndRead(java.nio.ByteBuffer src, int skip, java.nio.ByteBuffer dst) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
write(java.nio.ByteBuffer)
and
read(java.nio.ByteBuffer)
.src
- The buffer from which bytes are to be retrievedskip
- 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-1
if the device has reached end-of-streamjava.lang.NullPointerException
- If src
or dst
is null
.InvalidWordLengthException
- if the total number of bytes to receive or send belies word length.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.io.IOException
- If some other I/O error occursint writeAndRead(int txData) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
txData
- the word to send.java.io.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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.Copyright © 2012, 2014, Oracle and/or its affiliates. All rights reserved.
Legal Notices