ztex

Class Ztex1

java.lang.Object

ztex.Ztex1

All Implemented Interfaces:

HasName

Direct Known Subclasses:

Ztex1v1

public class Ztex1
extends java.lang.Object
implements HasName

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

Fields

Modifier and Type	Field and Description
int	controlMsgTimeout The timeout for control messages in ms.

Constructor Summary

Constructors

Constructor and Description
Ztex1(ZtexDevice1 pDev) Constructs an instance from a given device.

Method Summary

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.

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

Releases all resources.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

name

public java.lang.String name()

Returns the name of the device which is

dev().name())

.

Specified by:

name in interface HasName

Returns:

the name of the device.

See Also:

ZtexDevice1.name()

handle

public final org.usb4java.DeviceHandle handle()

Returns the USB file 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.

vendorCommand3

public void vendorCommand3(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 after one retry. 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.

vendorCommand3

public void vendorCommand3(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 after one retry. 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,
                           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.

vendorRequest3

public void vendorRequest3(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 after one retry. 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.

vendorRequest3

public void vendorRequest3(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 after one retry. 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.

vendorRequest3

public void vendorRequest3(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 after one retry. 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 length 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 reset the EZ-USB

UsbException - if a communication error occurs.

InvalidFirmwareException - if ZTEX descriptor 1 is not available.

DeviceLostException - if a device went lost after renumeration.

resetDevice

public void resetDevice(boolean force)
                 throws UsbException

Performs a configuration or bus reset. This method is used to synchronize data toggles at start-up of the host software.

Parameters:

force - True enforces a bus reset. By default a configuration reset is tried first and if it fails, a bus reset is performed.

Throws:

UsbException - if a communication error occurs.

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.