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
 boolean certainWorkarounds
          Setting to true enables certain workarounds, e.g. to deal with bad driver/OS implementations.
 int controlMsgTimeout
          The timeout for control messages in ms.
 
Constructor Summary
Ztex1(ZtexDevice1 pDev)
          Constructs an instance from a given device.
 
Method Summary
 void checkValid()
          Checks whether ZTEX descriptor 1 is available.
 void claimInterface(int iface)
          Claims an interface.
 ZtexDevice1 dev()
          Returns the corresponding ZtexDevice1.
protected  void finalize()
          The destructor closes the USB file handle.
 boolean getInterfaceClaimed(int iface)
          Returns true if interface is claimed.
 long 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 ihxIn, java.lang.String name, boolean force)
          Uploads the firmware to the EZ-USB and manages the renumeration process.
 long uploadFirmware(java.lang.String ihxFileName, boolean force)
          Uploads the firmware to the EZ-USB and manages the renumeration process.
 long uploadFirmware(ZtexIhxFile1 ihxFile, 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.
 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.
 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, int value, int index, byte[] buf, int maxlen)
          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, 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.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

certainWorkarounds

public boolean certainWorkarounds
Setting to true enables certain workarounds, e.g. to deal with bad driver/OS implementations.


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.

finalize

protected void finalize()
The destructor closes the USB file handle.

Overrides:
finalize in class java.lang.Object

handle

public final long 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,
                         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,
                         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,
                         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,
                           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,
                           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.

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 messaage 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(ZtexIhxFile1 ihxFile,
                           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:
ihxFile - 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 ihxFileName,
                           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:
ihxFileName - The file name of the firmware image in ihx 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 ihxIn,
                           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:
ihxIn - Input stream from which the ihx 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.