public class Ztex1 extends java.lang.Object implements HasName
All firmware implementations that provide the ZTEX descriptor 1 are supported.
A description of this descriptor can be found in ZtexDevice1
.
The most important features of this class are the functions for uploading the firmware and the renumeration management.
The interface dependent part of the communication protocol (currently only one is supported)
can be found in Ztex1v1
.
ZtexDevice1
,
Ztex1v1
Modifier and Type | Field and Description |
---|---|
int |
controlMsgTimeout
The timeout for control messages in ms.
|
Constructor and Description |
---|
Ztex1(ZtexDevice1 pDev)
Constructs an instance from a given device.
|
Modifier and Type | Method and Description |
---|---|
static java.nio.ByteBuffer |
allocateByteBuffer(byte[] buf)
Utility function that creates a ByteBuffer from byte array.
|
static java.nio.ByteBuffer |
allocateByteBuffer(byte[] buf,
int offs,
int length)
Utility function that creates a ByteBuffer from byte array.
|
int |
bulkRead(int ep,
byte[] buf,
int maxlen,
long timeout)
Wrapper method for LibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).
|
int |
bulkRead(int ep,
java.nio.ByteBuffer buffer,
long timeout)
Wrapper method for LibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).
|
int |
bulkWrite(int ep,
byte[] buf,
int length,
long timeout)
Wrapper method for LibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).
|
int |
bulkWrite(int ep,
java.nio.ByteBuffer buffer,
long timeout)
Wrapper method for ibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).
|
void |
checkValid()
Checks whether ZTEX descriptor 1 is available.
|
void |
claimInterface(int iface)
Claims an interface.
|
ZtexDevice1 |
dev()
Returns the corresponding
ZtexDevice1 . |
void |
dispose()
This should be called if the class is not used anymore.
|
protected void |
finalize()
Releases all resources.
|
boolean |
getInterfaceClaimed(int iface)
Returns true if interface is claimed.
|
org.usb4java.DeviceHandle |
handle()
Returns the USB file handle.
|
protected void |
init()
Initializates the class.
|
java.lang.String |
name()
Returns the name of the device which is dev().name()).
|
void |
releaseInterface(int iface)
Releases an interface.
|
void |
resetDevice(boolean force)
Performs a configuration or bus reset.
|
void |
resetEzUsb()
Resets the EZ-USB and manages the renumeration process.
|
void |
setConfiguration(int config)
Sets the configuration.
|
java.lang.String |
toString()
Returns a lot of useful information about the corresponding device.
|
void |
trySetConfiguration(int config)
Tries to set the configuration.
|
long |
uploadFirmware(java.io.InputStream imgIn,
java.lang.String name,
boolean force)
Uploads the firmware to the EZ-USB and manages the renumeration process.
|
long |
uploadFirmware(java.lang.String imgFileName,
boolean force)
Uploads the firmware to the EZ-USB and manages the renumeration process.
|
long |
uploadFirmware(ZtexImgFile1 imgFile,
boolean force)
Uploads the firmware to the EZ-USB and manages the renumeration process.
|
boolean |
valid()
Returns true if ZTEX descriptor 1 is available.
|
int |
vendorCommand(int cmd,
java.lang.String func)
Sends a vendor command with no payload data and no setup data to Endpoint 0 of the EZ-USB device.
|
int |
vendorCommand(int cmd,
java.lang.String func,
int value,
int index)
Sends a vendor command with no payload data to Endpoint 0 of the EZ-USB device.
|
int |
vendorCommand(int cmd,
java.lang.String func,
int value,
int index,
byte[] buf,
int length)
Sends a vendor command to Endpoint 0 of the EZ-USB device.
|
int |
vendorCommand(int cmd,
java.lang.String func,
int value,
int index,
java.nio.ByteBuffer buf)
Sends a vendor command to Endpoint 0 of the EZ-USB device.
|
void |
vendorCommand2(int cmd,
java.lang.String func,
int value,
int index,
byte[] buf,
int length)
Sends a vendor command to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been sent. |
void |
vendorCommand2(int cmd,
java.lang.String func,
int value,
int index,
java.nio.ByteBuffer buf)
Sends a vendor command to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been sent. |
void |
vendorCommand3(int cmd,
java.lang.String func,
int value,
int index,
byte[] buf,
int length)
Sends a vendor command to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been sent after one retry. |
void |
vendorCommand3(int cmd,
java.lang.String func,
int value,
int index,
java.nio.ByteBuffer buf)
Sends a vendor command to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been sent after one retry. |
int |
vendorRequest(int cmd,
java.lang.String func,
byte[] buf,
int maxlen)
Sends a vendor request to Endpoint 0 of the EZ-USB device.
|
int |
vendorRequest(int cmd,
java.lang.String func,
java.nio.ByteBuffer buf)
Sends a vendor request to Endpoint 0 of the EZ-USB device.
|
int |
vendorRequest(int cmd,
java.lang.String func,
int value,
int index,
byte[] buf,
int maxlen)
Sends a vendor request to Endpoint 0 of the EZ-USB device.
|
int |
vendorRequest(int cmd,
java.lang.String func,
int value,
int index,
java.nio.ByteBuffer buf)
Sends a vendor request to Endpoint 0 of the EZ-USB device.
|
void |
vendorRequest2(int cmd,
java.lang.String func,
byte[] buf,
int maxlen)
Sends a vendor request to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been received. |
void |
vendorRequest2(int cmd,
java.lang.String func,
java.nio.ByteBuffer buf)
Sends a vendor request to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been received. |
void |
vendorRequest2(int cmd,
java.lang.String func,
int value,
int index,
byte[] buf,
int maxlen)
Sends a vendor request to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been received. |
void |
vendorRequest3(int cmd,
java.lang.String func,
byte[] buf,
int maxlen)
Sends a vendor request to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been received after one retry. |
void |
vendorRequest3(int cmd,
java.lang.String func,
java.nio.ByteBuffer buf)
Sends a vendor request to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been received after one retry. |
void |
vendorRequest3(int cmd,
java.lang.String func,
int value,
int index,
byte[] buf,
int maxlen)
Sends a vendor request to Endpoint 0 of the EZ-USB device and throws an
UsbException if not all of the payload has been received after one retry. |
public Ztex1(ZtexDevice1 pDev) throws UsbException
pDev
- The given device.UsbException
- if an communication error occurred.protected void init() throws UsbException
UsbException
- if an communication error occurred.public void dispose()
protected void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
public java.lang.String name()
dev().name()).
name
in interface HasName
ZtexDevice1.name()
public final org.usb4java.DeviceHandle handle()
public final ZtexDevice1 dev()
ZtexDevice1
.ZtexDevice1
.public boolean valid()
public void checkValid() throws InvalidFirmwareException
InvalidFirmwareException
- if ZTEX descriptor 1 is not available.public int vendorCommand(int cmd, java.lang.String func, int value, int index, java.nio.ByteBuffer buf) throws UsbException
controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.buf
- The payload data buffer. The full buffer is sent, i.e. transfer size is equal to buffer capacity.UsbException
- if a communication error occurs.public int vendorCommand(int cmd, java.lang.String func, int value, int index, byte[] buf, int length) throws UsbException
controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.length
- The size of the payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs.public int vendorCommand(int cmd, java.lang.String func, int value, int index) throws UsbException
controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.UsbException
- if a communication error occurs.public int vendorCommand(int cmd, java.lang.String func) throws UsbException
controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.UsbException
- if a communication error occurs.public int vendorRequest(int cmd, java.lang.String func, int value, int index, java.nio.ByteBuffer buf) throws UsbException
controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.buf
- The payload data buffer. Buffer capacity determines the length of the transfer.UsbException
- if a communication error occurs.public int vendorRequest(int cmd, java.lang.String func, int value, int index, byte[] buf, int maxlen) throws UsbException
controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.maxlen
- The size of the requested payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs.public int vendorRequest(int cmd, java.lang.String func, java.nio.ByteBuffer buf) throws UsbException
controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.buf
- The payload data buffer.UsbException
- if a communication error occurs.public int vendorRequest(int cmd, java.lang.String func, byte[] buf, int maxlen) throws UsbException
controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.maxlen
- The size of the requested payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs.public void vendorCommand2(int cmd, java.lang.String func, int value, int index, java.nio.ByteBuffer buf) throws UsbException
UsbException
if not all of the payload has been sent.
The command may be send multiple times until the controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.buf
- The payload data buffer. The full buffer is sent, i.e. transfer size is equal to buffer capacity.UsbException
- if a communication error occurs or if not all of the payload has been sent.public void vendorCommand2(int cmd, java.lang.String func, int value, int index, byte[] buf, int length) throws UsbException
UsbException
if not all of the payload has been sent.
The command may be send multiple times until the controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.length
- The size of the payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs or if not all of the payload has been sent.public void vendorCommand3(int cmd, java.lang.String func, int value, int index, java.nio.ByteBuffer buf) throws UsbException
UsbException
if not all of the payload has been sent after one retry.
The command may be send multiple times until the controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.buf
- The payload data buffer. The full buffer is sent, i.e. transfer size is equal to buffer capacity.UsbException
- if a communication error occurs or if not all of the payload has been sent.public void vendorCommand3(int cmd, java.lang.String func, int value, int index, byte[] buf, int length) throws UsbException
UsbException
if not all of the payload has been sent after one retry.
The command may be send multiple times until the controlMsgTimeout
is reached.cmd
- The command number (0..255).func
- The name of the command. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.length
- The size of the payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs or if not all of the payload has been sent.public void vendorRequest2(int cmd, java.lang.String func, java.nio.ByteBuffer buf) throws UsbException
UsbException
if not all of the payload has been received.
The request may be send multiple times until the controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.buf
- The payload data buffer.UsbException
- if a communication error occurs or not all of the payload has been received.public void vendorRequest2(int cmd, java.lang.String func, int value, int index, byte[] buf, int maxlen) throws UsbException
UsbException
if not all of the payload has been received.
The request may be send multiple times until the controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.maxlen
- The size of the requested payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs or not all of the payload has been received.public void vendorRequest2(int cmd, java.lang.String func, byte[] buf, int maxlen) throws UsbException
UsbException
if not all of the payload has been received.
The request may be send multiple times until the controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.maxlen
- The size of the requested payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs or not all of the payload has been received.public void vendorRequest3(int cmd, java.lang.String func, java.nio.ByteBuffer buf) throws UsbException
UsbException
if not all of the payload has been received after one retry.
The request may be send multiple times until the controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.buf
- The payload data buffer.UsbException
- if a communication error occurs or not all of the payload has been received.public void vendorRequest3(int cmd, java.lang.String func, int value, int index, byte[] buf, int maxlen) throws UsbException
UsbException
if not all of the payload has been received after one retry.
The request may be send multiple times until the controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.value
- The value (0..65535), i.e bytes 2 and 3 of the setup data.index
- The index (0..65535), i.e. bytes 4 and 5 of the setup data.maxlen
- The size of the requested payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs or not all of the payload has been received.public void vendorRequest3(int cmd, java.lang.String func, byte[] buf, int maxlen) throws UsbException
UsbException
if not all of the payload has been received after one retry.
The request may be send multiple times until the controlMsgTimeout
is reached.cmd
- The request number (0..255).func
- The name of the request. This string is used for the generation of error messages.maxlen
- The size of the requested payload data (0..65535), i.e. bytes 6 and 7 of the setup data.buf
- The payload data buffer.UsbException
- if a communication error occurs or not all of the payload has been received.public int bulkWrite(int ep, java.nio.ByteBuffer buffer, long timeout)
ep
- The endpoint number.buffer
- The payload data buffer. The whole buffer is transferred, i.e. transfer length is equal to buffer capacitytimeout
- The timeout in mspublic int bulkWrite(int ep, byte[] buf, int length, long timeout)
ep
- The endpoint number.buf
- The payload data buffer.length
- The size of the payload datatimeout
- The timeout in mspublic int bulkRead(int ep, java.nio.ByteBuffer buffer, long timeout)
ep
- The endpoint number.buffer
- The payload data buffer. The transfer length is determined by buffer capacity.timeout
- The timeout in mspublic int bulkRead(int ep, byte[] buf, int maxlen, long timeout)
ep
- The endpoint number.buf
- The payload data buffer.maxlen
- The size of the transfer.timeout
- The timeout in mspublic static java.nio.ByteBuffer allocateByteBuffer(byte[] buf)
buf
- The byte array.public static java.nio.ByteBuffer allocateByteBuffer(byte[] buf, int offs, int length)
buf
- The byte array.offs
- The offset of the first data in the byte array.length
- Length of the The byte array.public void setConfiguration(int config) throws UsbException
config
- The configuration number (usually 1)UsbException
- if an error occurs while attempting to set the configuration.public void trySetConfiguration(int config)
config
- The configuration number (usually 1)public boolean getInterfaceClaimed(int iface)
iface
- The interface numberpublic void claimInterface(int iface) throws UsbException
iface
- The interface number (usually 0)UsbException
- if an error occurs while attempting to claim the interface.public void releaseInterface(int iface)
iface
- The interface number (usually 0)public long uploadFirmware(ZtexImgFile1 imgFile, boolean force) throws IncompatibleFirmwareException, FirmwareUploadException, UsbException, InvalidFirmwareException, DeviceLostException
Before the firmware is uploaded the device is set into a reset state. After the upload the firmware is booted and the renumeration starts. During this process the device disappears from the bus and a new one occurs which will be assigned to this class automatically (instead of the disappeared one).
imgFile
- The firmware image.force
- The compatibility check is skipped if true.IncompatibleFirmwareException
- if the given firmware is not compatible to the installed one, see ZtexDevice1.compatible(int,int,int,int)
(Upload can be enforced using the force parameter)FirmwareUploadException
- If an error occurred while attempting to upload the firmware.UsbException
- if a communication error occurs.InvalidFirmwareException
- if ZTEX descriptor 1 is not available.DeviceLostException
- if a device went lost after renumeration.public long uploadFirmware(java.lang.String imgFileName, boolean force) throws IncompatibleFirmwareException, FirmwareUploadException, UsbException, InvalidFirmwareException, DeviceLostException
Before the firmware is uploaded the device is set into a reset state. After the upload the firmware is booted and the renumeration starts. During this process the device disappears from the bus and a new one occurs which will be assigned to this class automatically (instead of the disappeared one).
imgFileName
- The file name of the firmware image in ihx or img format. The file can be a regular file or a system resource (e.g. a file from the current jar archive).force
- The compatibility check is skipped if true.IncompatibleFirmwareException
- if the given firmware is not compatible to the installed one, see ZtexDevice1.compatible(int,int,int,int)
(Upload can be enforced using the force parameter)FirmwareUploadException
- If an error occurred while attempting to upload the firmware.UsbException
- if a communication error occurs.InvalidFirmwareException
- if ZTEX descriptor 1 is not available.DeviceLostException
- if a device went lost after renumeration.public long uploadFirmware(java.io.InputStream imgIn, java.lang.String name, boolean force) throws IncompatibleFirmwareException, FirmwareUploadException, UsbException, InvalidFirmwareException, DeviceLostException
Before the firmware is uploaded the device is set into a reset state. After the upload the firmware is booted and the renumeration starts. During this process the device disappears from the bus and a new one occurs which will be assigned to this class automatically (instead of the disappeared one).
imgIn
- Input stream from which the img file is read.name
- Name of the input.force
- The compatibility check is skipped if true.IncompatibleFirmwareException
- if the given firmware is not compatible to the installed one, see ZtexDevice1.compatible(int,int,int,int)
(Upload can be enforced using the force parameter)FirmwareUploadException
- If an error occurred while attempting to upload the firmware.UsbException
- if a communication error occurs.InvalidFirmwareException
- if ZTEX descriptor 1 is not available.DeviceLostException
- if a device went lost after renumeration.public void resetEzUsb() throws FirmwareUploadException, UsbException, InvalidFirmwareException, DeviceLostException
After the reset the renumeration starts. During this process the device disappears from the bus and a new one occurs which will be assigned to this class automatically (instead of the disappeared one).
FirmwareUploadException
- If an error occurred while attempting to reset the EZ-USBUsbException
- if a communication error occurs.InvalidFirmwareException
- if ZTEX descriptor 1 is not available.DeviceLostException
- if a device went lost after renumeration.public void resetDevice(boolean force) throws UsbException
force
- True enforces a bus reset. By default a configuration reset is tried first and if it fails, a bus reset is performed.UsbException
- if a communication error occurs.public java.lang.String toString()
toString
in class java.lang.Object