public interface SPICompositeMessage
SPICompositeMessage interface provides methods for constructing a
composite message. A composite message may be constituted of a sequence of read
and/or write operations to a single SPI slave device that will be performed as
a single transaction.
Here is an example of a composite message to a single slave:
try (SPIDevice slave = DeviceManager.open("SPI1", SPIDevice.class, null)) {
ByteBuffer sndBuf1 = ByteBuffer.wrap(new byte[] {0x01});
ByteBuffer sndBuf2 = ByteBuffer.wrap(new byte[] {0x02});
ByteBuffer rcvBuf = ByteBuffer.wrap(new byte[3]);
int bytesRead = slave.createCompositeMessage()
.appendwrite(sndBuf1)
.appendDelay(100)
.appendwriteAndRead(sndBuf2, rcvBuf)
.transfer()[0];
} catch (IOException ioe) {
// Handle exception
}
The preceding example is using a
try-with-resources statement; the
SPIDevice.close method is automatically invoked by
the platform at the end of the statement.
| Modifier and Type | Method and Description |
|---|---|
SPICompositeMessage |
appendDelay(int delay)
Appends a delay (in microseconds).
|
SPICompositeMessage |
appendRead(ByteBuffer rxBuf)
Appends a read message/operation from the targeted SPI slave device.
|
SPICompositeMessage |
appendRead(int rxSkip,
ByteBuffer rxBuf)
Appends a read message/operation from the targeted SPI slave device.
|
SPICompositeMessage |
appendWrite(ByteBuffer txBuf)
Appends a write message/operation from the targeted SPI slave device.
|
SPICompositeMessage |
appendWriteAndRead(ByteBuffer src,
ByteBuffer dst)
Appends an exchange message/operation from the targeted SPI slave device.
|
SPICompositeMessage |
appendWriteAndRead(ByteBuffer src,
int skip,
ByteBuffer dst)
Appends an exchange message/operation with the targeted SPI slave device.
|
SPIDevice |
getTargetedDevice()
Gets the
SPIDevice this composite message is targeting. |
int[] |
transfer()
Transfers this composite message to the targeted
SPIDevice. |
SPICompositeMessage appendRead(ByteBuffer rxBuf) throws IOException, ClosedDeviceException
rxBuf.remaining() bytes of data from the targeted slave
device into the buffer rxBuf.
Upon the invocation of the transfer method
the appended operation will have a behavior equivalent to that of the invocation of the
SPIDevice.read(org.joshvm.util.ByteBuffer) method on the targeted SPIDevice.
Buffers are not safe for use by multiple concurrent threads so care should
be taken to not access the provided buffer until the operation has completed - that
is: until the transfer method has been invoked and has returned.
rxBuf - the buffer into which the data is read.SPICompositeMessage object.NullPointerException - if rxBuf is null.IllegalStateException - if this message has already been assembled
and transferred once.ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.SPICompositeMessage appendRead(int rxSkip, ByteBuffer rxBuf) throws IOException, ClosedDeviceException
rxBuf.remaining() bytes of data from the targeted slave
device into the buffer skipping rxBuf the first rxSkip
bytes read.
Upon the invocation of the transfer method
the appended operation will have a behavior equivalent to that of the invocation of the
SPIDevice.read(int, org.joshvm.util.ByteBuffer) method on the targeted SPIDevice.
Buffers are not safe for use by multiple concurrent threads so care should
be taken to not access the provided buffer until the operation has completed - that
is: until the transfer method has been invoked and has returned.
rxSkip - the number of read bytes that must be ignored/skipped
before filling in the rxBuf buffer.rxBuf - the buffer into which the data is read.SPICompositeMessage object.NullPointerException - if rxBuf is null.IllegalStateException - if this message has already been assembled
and transferred once.ClosedDeviceException - if the device has been closed.IllegalArgumentException - if rxSkip is negative.IOException - if some other I/O error occurs.SPICompositeMessage appendWrite(ByteBuffer txBuf) throws IOException, ClosedDeviceException
txBuf.remaining() bytes from the
buffer txBuf.
Upon the invocation of the transfer method
the appended operation will have a behavior equivalent to that of the invocation of the
SPIDevice.write(org.joshvm.util.ByteBuffer) method on the targeted SPIDevice.
Buffers are not safe for use by multiple concurrent threads so care should
be taken to not access the provided buffer until the operation has completed - that
is: until the transfer method has been invoked and has returned.
txBuf - the buffer containing the bytes to write.SPICompositeMessage object.NullPointerException - if txBuf is null.IllegalStateException - if this message has already been assembled
and transferred once.ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occurs.SPICompositeMessage appendWriteAndRead(ByteBuffer src, ByteBuffer dst) throws IOException, ClosedDeviceException
Upon the invocation of the transfer method
the appended operation will have a behavior equivalent to that of the invocation of the
SPIDevice#writeAndRead(org.joshvm.util.ByteBuffer, com.joshvm.util.ByteBuffer)
method on the targeted SPIDevice.
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.
Buffers are not safe for use by multiple concurrent threads so care should
be taken to not access the provided buffer until the operation has completed - that
is: until the transfer method has been invoked and has returned.
src - The buffer from which bytes are to be retrieved.dst - The buffer into which bytes are to be transferred.SPICompositeMessage object.NullPointerException - if src or dst is null.IllegalStateException - if this message has already been assembled
and transferred once.ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occursSPICompositeMessage appendWriteAndRead(ByteBuffer src, int skip, ByteBuffer dst) throws IOException, ClosedDeviceException
Upon the invocation of the transfer method
the appended operation will have a behavior equivalent to that of the invocation of the
SPIDevice#writeAndRead(org.joshvm.util.ByteBuffer, int, com.joshvm.util.ByteBuffer)
method on the targeted SPIDevice.
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.
Buffers are not safe for use by multiple concurrent threads so care should
be taken to not access the provided buffer until the operation has completed - that
is: until the transfer method has been invoked and has returned.
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.SPICompositeMessage object.NullPointerException - if src or dst is null.IllegalArgumentException - if skip is negative.IllegalStateException - if this message has already been assembled
and transferred once.ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occursSPICompositeMessage appendDelay(int delay) throws IOException, ClosedDeviceException
Upon the invocation of the transfer method
the next operation (or the completion of this composite message transfer if this
is the last operation) will be delayed by the specified amount of microseconds.
If the underlying platform or driver does not support a microsecond timer resolution
or does not support the requested delay value then delay will be rounded up
to accommodate the supported timer resolution or the closest greater supported discrete delay value, if any.
delay - the amount (in microseconds) to delay the next operation.SPICompositeMessage object.IllegalArgumentException - if delay is negative or cannot be accommodated for by rounding it up to
a supported value.IllegalStateException - if this message has already been assembled
and transferred once.ClosedDeviceException - if the device has been closed.IOException - if some other I/O error occursint[] transfer()
throws IOException,
UnavailableDeviceException,
ClosedDeviceException
SPIDevice. This will result in each of the
contained messages/operations to be sent/executed in the same order they
have been appended to this composite message.
This method may be invoked at any time. If another thread has already initiated a transaction
(see jdk.dio.Transactional) or, a read or write operation upon the targeted slave device,
however, then an invocation of this method will block until the first operation is complete.
Once transferred no additional operation can be appended anymore to this
composite message. Any such attempt will result in a
IllegalStateException to be thrown.
Nevertheless, this SPICompositeMessage object can be reused several times to perform
the same sequence of operations. The data transferred
to or from each of the provided ByteBuffers is determined by their respective current position
and remaining attributes at the time this method is call.
Buffers are not safe for use by multiple concurrent threads so care should
be taken to not access the provided buffers until the transfer has completed.
InvalidWordLengthException - if the total number of bytes to receive
or send of any of the appended operations belies word length.UnavailableDeviceException - if the targeted devices is not
currently available - such as it is locked by another application.ClosedDeviceException - if the targeted device is has been closed.IOException - if some other I/O error occurredSPIDevice getTargetedDevice()
SPIDevice this composite message is targeting.