ztex
Class Ztex1

java.lang.Object
  extended by ztex.Ztex1
Direct Known Subclasses:
Ztex1v1

public class Ztex1
extends java.lang.Object

This class implements the interface-independent part of the communication protocol for the interaction with the ZTEX firmware.

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.

See Also:
ZtexDevice1, Ztex1v1

Field Summary
 int controlMsgTimeout
          The timeout for control messages in ms.
 
Constructor Summary
Ztex1(ZtexDevice1 pDev)
          Constructs an instance from a given device.
 
Method Summary
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()
           
 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.
 void releaseInterface(int iface)
          Releases an interface.
 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.
 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 vendorRequest2(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 and throws an UsbException if not all of the payload has been received.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

controlMsgTimeout

public int controlMsgTimeout
The timeout for control messages in ms.

Constructor Detail

Ztex1

public Ztex1(ZtexDevice1 pDev)
      throws UsbException
Constructs an instance from a given device.

Parameters:
pDev - The given device.
Throws:
UsbException - if an communication error occurred.
Method Detail

init

protected void init()
             throws UsbException
Initializates the class.

Throws:
UsbException - if an communication error occurred.

dispose

public void dispose()
This should be called if the class is not used anymore. It closes the USB connection and releases all resources


finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object
Throws:
java.lang.Throwable

handle

public final org.usb4java.DeviceHandle handle()
Returns the USB file handle.


dev

public final ZtexDevice1 dev()
Returns the corresponding ZtexDevice1.

Returns:
the corresponding ZtexDevice1.

valid

public boolean valid()
Returns true if ZTEX descriptor 1 is available.

Returns:
true if ZTEX descriptor 1 is available.

checkValid

public void checkValid()
                throws InvalidFirmwareException
Checks whether ZTEX descriptor 1 is available.

Throws:
InvalidFirmwareException - if ZTEX descriptor 1 is not available.

vendorCommand

public int vendorCommand(int cmd,
                         java.lang.String func,
                         int value,
                         int index,
                         java.nio.ByteBuffer buf)
                  throws UsbException
Sends a vendor command to Endpoint 0 of the EZ-USB device. The command may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes sent.
Throws:
UsbException - if a communication error occurs.

vendorCommand

public int vendorCommand(int cmd,
                         java.lang.String func,
                         int value,
                         int index,
                         byte[] buf,
                         int length)
                  throws UsbException
Sends a vendor command to Endpoint 0 of the EZ-USB device. The command may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes sent.
Throws:
UsbException - if a communication error occurs.

vendorCommand

public int vendorCommand(int cmd,
                         java.lang.String func,
                         int value,
                         int index)
                  throws UsbException
Sends a vendor command with no payload data to Endpoint 0 of the EZ-USB device. The command may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes sent.
Throws:
UsbException - if a communication error occurs.

vendorCommand

public int vendorCommand(int cmd,
                         java.lang.String func)
                  throws UsbException
Sends a vendor command with no payload data and no setup data to Endpoint 0 of the EZ-USB device. The command may be send multiple times until the controlMsgTimeout is reached.

Parameters:
cmd - The command number (0..255).
func - The name of the command. This string is used for the generation of error messages.
Returns:
the number of bytes sent.
Throws:
UsbException - if a communication error occurs.

vendorRequest

public int vendorRequest(int cmd,
                         java.lang.String func,
                         int value,
                         int index,
                         java.nio.ByteBuffer buf)
                  throws UsbException
Sends a vendor request to Endpoint 0 of the EZ-USB device. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes received.
Throws:
UsbException - if a communication error occurs.

vendorRequest

public int vendorRequest(int cmd,
                         java.lang.String func,
                         int value,
                         int index,
                         byte[] buf,
                         int maxlen)
                  throws UsbException
Sends a vendor request to Endpoint 0 of the EZ-USB device. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes received.
Throws:
UsbException - if a communication error occurs.

vendorRequest

public int vendorRequest(int cmd,
                         java.lang.String func,
                         java.nio.ByteBuffer buf)
                  throws UsbException
Sends a vendor request to Endpoint 0 of the EZ-USB device. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes sent.
Throws:
UsbException - if a communication error occurs.

vendorRequest

public int vendorRequest(int cmd,
                         java.lang.String func,
                         byte[] buf,
                         int maxlen)
                  throws UsbException
Sends a vendor request to Endpoint 0 of the EZ-USB device. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Returns:
the number of bytes sent.
Throws:
UsbException - if a communication error occurs.

vendorCommand2

public void vendorCommand2(int cmd,
                           java.lang.String func,
                           int value,
                           int index,
                           java.nio.ByteBuffer buf)
                    throws UsbException
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. The command may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Throws:
UsbException - if a communication error occurs or if not all of the payload has been sent.

vendorCommand2

public void vendorCommand2(int cmd,
                           java.lang.String func,
                           int value,
                           int index,
                           byte[] buf,
                           int length)
                    throws UsbException
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. The command may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Throws:
UsbException - if a communication error occurs or if not all of the payload has been sent.

vendorRequest2

public void vendorRequest2(int cmd,
                           java.lang.String func,
                           int value,
                           int index,
                           java.nio.ByteBuffer buf)
                    throws UsbException
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. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Throws:
UsbException - if a communication error occurs or not all of the payload has been received.

vendorRequest2

public void vendorRequest2(int cmd,
                           java.lang.String func,
                           java.nio.ByteBuffer buf)
                    throws UsbException
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. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Throws:
UsbException - if a communication error occurs or not all of the payload has been received.

vendorRequest2

public void vendorRequest2(int cmd,
                           java.lang.String func,
                           int value,
                           int index,
                           byte[] buf,
                           int maxlen)
                    throws UsbException
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. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Throws:
UsbException - if a communication error occurs or not all of the payload has been received.

vendorRequest2

public void vendorRequest2(int cmd,
                           java.lang.String func,
                           byte[] buf,
                           int maxlen)
                    throws UsbException
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. The request may be send multiple times until the controlMsgTimeout is reached.

Parameters:
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.
Throws:
UsbException - if a communication error occurs or not all of the payload has been received.

bulkWrite

public int bulkWrite(int ep,
                     java.nio.ByteBuffer buffer,
                     long timeout)
Wrapper method for ibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).

Parameters:
ep - The endpoint number.
buffer - The payload data buffer. The whole buffer is transferred, i.e. transfer legth is equal to buffer capacity
timeout - The timeout in ms
Returns:
The error code (<0) if an error occurred, otherwise the amount of transferred date

bulkWrite

public int bulkWrite(int ep,
                     byte[] buf,
                     int length,
                     long timeout)
Wrapper method for LibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).

Parameters:
ep - The endpoint number.
buf - The payload data buffer.
length - The size of the payload data
timeout - The timeout in ms
Returns:
The error code (<0) if an error occurred, otherwise the amount of transferred date

bulkRead

public int bulkRead(int ep,
                    java.nio.ByteBuffer buffer,
                    long timeout)
Wrapper method for LibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).

Parameters:
ep - The endpoint number.
buffer - The payload data buffer. The transfer length is determined by buffer capacity.
timeout - The timeout in ms
Returns:
The error code (<0) if an error occurred, otherwise the amount of transferred date

bulkRead

public int bulkRead(int ep,
                    byte[] buf,
                    int maxlen,
                    long timeout)
Wrapper method for LibUsb.bulkTransfer(DeviceHandle,byte,ByteBuffer,IntBuffer,long).

Parameters:
ep - The endpoint number.
buf - The payload data buffer.
maxlen - The size of the transfer.
timeout - The timeout in ms
Returns:
The error code (<0) if an error occurred, otherwise the amount of transferred date

allocateByteBuffer

public static java.nio.ByteBuffer allocateByteBuffer(byte[] buf)
Utility function that creates a ByteBuffer from byte array.

Parameters:
buf - The byte array.
Returns:
A ByteBuffer .

allocateByteBuffer

public static java.nio.ByteBuffer allocateByteBuffer(byte[] buf,
                                                     int offs,
                                                     int length)
Utility function that creates a ByteBuffer from byte array.

Parameters:
buf - The byte array.
offs - The offset of the first data in the byte array.
length - Length of the The byte array.
Returns:
A ByteBuffer.

setConfiguration

public void setConfiguration(int config)
                      throws UsbException
Sets the configuration.

Parameters:
config - The configuration number (usually 1)
Throws:
UsbException - if an error occurs while attempting to set the configuration.

trySetConfiguration

public void trySetConfiguration(int config)
Tries to set the configuration. If an error occurs while attempting to set the configuration, a warning message is printed to stderr.

Parameters:
config - The configuration number (usually 1)

getInterfaceClaimed

public boolean getInterfaceClaimed(int iface)
Returns true if interface is claimed.

Parameters:
iface - The interface number
Returns:
true if interface is claimed

claimInterface

public void claimInterface(int iface)
                    throws UsbException
Claims an interface.

Parameters:
iface - The interface number (usually 0)
Throws:
UsbException - if an error occurs while attempting to claim the interface.

releaseInterface

public void releaseInterface(int iface)
Releases an interface.

Parameters:
iface - The interface number (usually 0)

uploadFirmware

public long uploadFirmware(ZtexImgFile1 imgFile,
                           boolean force)
                    throws IncompatibleFirmwareException,
                           FirmwareUploadException,
                           UsbException,
                           InvalidFirmwareException,
                           DeviceLostException
Uploads the firmware to the EZ-USB and manages the renumeration process.

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).

Parameters:
imgFile - The firmware image.
force - The compatibility check is skipped if true.
Returns:
the upload time in ms.
Throws:
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.

uploadFirmware

public long uploadFirmware(java.lang.String imgFileName,
                           boolean force)
                    throws IncompatibleFirmwareException,
                           FirmwareUploadException,
                           UsbException,
                           InvalidFirmwareException,
                           DeviceLostException
Uploads the firmware to the EZ-USB and manages the renumeration process.

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).

Parameters:
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.
Returns:
the upload time in ms.
Throws:
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.

uploadFirmware

public long uploadFirmware(java.io.InputStream imgIn,
                           java.lang.String name,
                           boolean force)
                    throws IncompatibleFirmwareException,
                           FirmwareUploadException,
                           UsbException,
                           InvalidFirmwareException,
                           DeviceLostException
Uploads the firmware to the EZ-USB and manages the renumeration process.

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).

Parameters:
imgIn - Input stream from which the img file is read.
name - Name of the input.
force - The compatibility check is skipped if true.
Returns:
the upload time in ms.
Throws:
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.

resetEzUsb

public void resetEzUsb()
                throws FirmwareUploadException,
                       UsbException,
                       InvalidFirmwareException,
                       DeviceLostException
Resets the EZ-USB and manages the renumeration process.

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).

Throws:
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.

toString

public java.lang.String toString()
Returns a lot of useful information about the corresponding device.

Overrides:
toString in class java.lang.Object
Returns:
a lot of useful information about the corresponding device.