Device description:

Get whatever linux know about the device:

$ lsusb -v

Uhm... what?

Figuring out what that is supposed to tell me via http://www.beyondlogic.org/usbnutshell/usb5.shtml

Diving in, starting with the top-level

Device descriptor

FL593 protocol details: http://www.teamwavelength.com/permanent/usb/docs/api/weiprot.html

"0x2000 Laser diode driver evaluation boards. Evaluation boards are typically for components or modules, and include supporting external circuitry and connectors required to quickly connect and begin operating the product."

Configuration descriptor

Interface descriptor

Endpoint descriptors

Devices that implement Wavelength's USB Protocol must support three endpoints. The control endpoint, endpoint 0, must always be supported by all devices. In addition to the control endpoint, endpoint 1 must be configured in the device to support interrupt OUT transfers, and endpoint 2 must be configured to support interrupt IN transfers. The control endpoint is used only by the device driver and Windows during enumeration of the device. Once the device has enumerated, the device driver performs all device IO operations using the interrupt endpoints. For each command packet submitted to the device driver, the device driver transmits an interrupt OUT transfer to the device. Every time a user mode application requests the corresponding response packet, the device driver initiates an interrupt IN transfer, reading data from the device, and populates the buffer specified in the application's read call to the driver with the data received from the device.

from: http://www.teamwavelength.com/permanent/usb/docs/api/driver.html

Endpoint 1 descriptor (OUTPUT TO DEVICE)

Endpoint Address:

Bits 0..3b Endpoint Number.

Bits 4..6b Reserved. Set to Zero

Bits 7 Direction 0 = Out, 1 = In (Ignored for Control Endpoints)

Attributes bitmap:

Bits 0..1 Transfer Type

00 = Control
01 = Isochronous
10 = Bulk
11 = Interrupt

Bits 2..7 are reserved. If Isochronous endpoint, Bits 3..2 = Synchronisation Type (Iso Mode)

00 = No Synchonisation
01 = Asynchronous
10 = Adaptive
11 = Synchronous

Bits 5..4 = Usage Type (Iso Mode)

00 = Data Endpoint
01 = Feedback Endpoint
10 = Explicit Feedback Data Endpoint
11 = Reserved

Endpoint 2 descriptor (INPUT TO HOST)

Command and response packet structure

from: http://www.teamwavelength.com/permanent/usb/docs/api/driver.html

DevType field

The DevType field indicates the type of device being accessed. This field is used by combinational devices, such as those that include a temperature controller and laser driver in the same package with a single USB interface. The DevType field can be set to a value indicating which element of the product an operation is targetting, allowing for the command code value set for each element of the product to overlap each other, and therefore match more closely the command set implemented by other Wavelength products. For products that only contain a single type of product, this field is generally ignored.

Channel field

The Channel field allows a specific channel to be targetting in a multichannel product. For example, the FL593FL dual channel laser driver has two separate channels which can be independently controlled. By specifying a channel number in this field, software can gain control over the operation of each channel. A value of 0 indicates that the target of an operation is the device itself, rather than a channel within the device.

OpType field

The OpType field indicates the type of operation requested. The possible values are 1 (TYPE_READ), 2 (TYPE_WRITE), 3 (TYPE_MIN) and 4 (TYPE_MAX). The TYPE_READ OpType value indicates that the host application wishes to read the current value for the parameter specified by the OpCode field, for example, to read what the setpoint currently is for the device. The TYPE_WRITE OpType value indicates that the host application wishes to set a new value for the parameter specified in the OpCode field. The TYPE_MIN and TYPE_MAX OpType values can be used by the host application to determine what the minimum and maximum acceptable values are for the parameter indicated in the OpCode field.

OpCode field

The OpCode field indicates the parameter of interest for the requested operation. Each requested operation, such as accessing the setpoint, limits, monitor feedbacks, operation mode controls, status flags, etc will have a specific OpCode value assigned to it. The Wavelength USB Device Protocol defines the OpCode range of 0x00 to 0x0F (inclusive) as command codes that must be supported by all devices that use the WEIUSB.SYS device driver to allow for identification of devices. OpCode values greater than or equal to 0x10 define codes specific to a particular product or type of product. For more information on these OpCode values, please refer to the datasheet for the specific product of interest.

Data field

The Data field allows the host application to transmit up to 16 bytes of information to the device. The contents of the Data field depends on the operation requested. For example, when setting the the setpoint for a device, the data field will contain the new setpoint value in units defined by the product implementation. For OpType values of TYPE_READ, TYPE_MIN and TYPE_MAX, the contents of the Data field in the command packet are ignored.

from: http://www.teamwavelength.com/permanent/usb/docs/api/weiprot.html

Command packet:

The command packet represents information sent by software running on the host computer to the device to instruct it to perform some action. This packet is transfered as binary data. The following table illustrates the internal structure of a command packet as it is transmitted on the bus:

The following table describes each field in more detail:

The OpType field can have one of the four following values:

The TypeMin and TypeMax OpType values are used for detecting the capabilities of a device that is not necessarily known to software. These OpTypes instruct the device to return back to the host application the acceptable values for a quantity specified in OpCode, allowing an existing application to work with similar products as they are released in the future.

Response Packet

The response packet represents information read from a device to the host by the driver. Its internal structure is nearly identical to that of the command packet, with the exception of the addition of a 2-byte EndCode field. The following table outlines this internal structure:

The following table describes each field in more detail:

The following table outlines the generic end codes that can possibly be returned from any device supporting the Wavelength USB Device Protocol:

When a response packet is returned to the host, most of the fields will contain the values specified in the respective response packet. This allows the host application to determine exactly which operation was completed. This is useful in applications where there is a delay between sending the command packet and retrieving the response packet. For command packets where OpType is set to TypeWrite, the data field of the response packet will contain the current value of the specified quantity after applying the value specified by the command. For OpType of TypeRead, the value of the data field is the current value known to the device for the specified quantity.

OpCode Values

As mentioned previously, there is a basic set of OpCodes that must be supported by all devices utilizing this protocol. These OpCodes are used to determine the product ID of the device, serial number, model number, and other information identifying the device. The following table outlines these OpCodes:

Notes:

-TypeWrite OpType value is only valid when the device is in calibration mode. -Devices that do not contain nonvolatile memory must still acknowledge the SAVE request successfully, as the SAVE command falls within the range of codes (0x00-0x0F) that must be supported by all devices.

Data Field Formatting

The data field for any given command or response packet is a 16-byte buffer that can be applied as needed by any function provided by a particular device. The data field should be used to transfer data by means that are platform independent to avoid the need to manage byte-ordering within the data field. There are four primary types of data that can be transferred in the data field: string, numeric, boolean and bitmapped.

String data allows for the transfer of data that contains characters that cannot be interpreted or represented as numeric data. This includes the characters A-Z, a-z, punctuation marks and whitespace. String data is used to represent the model number, serial number and possibly the firmware version. All data in a string data field are left-aligned, and unused bytes in the data field must be padded with NULL characters (ASCII 0).

Numeric data is any data that can be evaluated as or converted to numeric form. This includes all real numbers. Any measured quantities, such as current monitors, temperature monitors and power monitors all will return unitless values in the data field, however this value will be scaled to units of the quantity measured. For example, if a laser driver's current monitor is set to 100mA, the data field when requesting the current monitor value will be represented in units of amperes. Similarly, photodiode current will be represented in amps for laser drivers. Temperature controllers will have the option of representing temperatures in either volts or degrees Celsius, since converting the measured feedback in volts to degrees Celsius cannot be done without additional information about the temperature sensor that the user may not possess or may not be readily available.

Boolean data represents a single boolean term. The data field will use left-aligned data within the data field, and only the left-most character will contain data. The remaining characters may contain additional information, however it will be ignored. See the data sheet for specific USB based products to see which commands utilize boolean data. With a boolean term, a value of zero indicates a logical false, and a nonzero value indicates true.

The final data format is the bitmapped format. The bitmapped type is similar to boolean, except that it utilizes all 16 of the data field characters instead of just the first (position 0). Just as with the boolean type, each character within the bitmap field is represented either as a '0' (ASCII 48) or any other numerical character, including '1' (ASCII 49) through '9' (ASCII 57). This is useful for commands such as the ALARM command, where multiple boolean values such as output state, enabled state, interlock state and limit flags are transferred at one time. A value of '0' in any given character indicates a logical false, and any other numeric value from '1' to '9' (inclusive) are considered to be a logical true. Any other character is considered illegal, and command packets containing any other characters will return a response packet with an end code of ERR_DATA. This allows up to 16 boolean quantities to be transferred in a bitmapped data transfer.