USB Device Level Documentation

Getting Started

See if you can turn the SLO-scope on, by issuing this USB control transfer: bmRequestType=0x40, bRequest=0x82 (REQUEST_SET_VARIABLE), wValue=1 (SLOSCOPE_STATE_2ANALOG), wIndex=0x42 (VARIABLE_SLOSCOPE_STATE), wLength=0, no data phase. If you succeed, then the yellow LED of the programmer should be on solid.

Reading Data from the Slo-scope

To read data from the slo-scope, you must use the REQUEST_SET_VARIABLE request to set VARIABLE_SLOSCOPE_STATE, as above. Then you can read data from Endpoint 5 IN. This is an interrupt endpoint. A new packet of slo-scope data will be available every millisecond.

Each packet is 22 bytes long. The first byte is the number of missed readings (readings that had to be discarded because there was no USB buffer available for them) between the time the last packet was finished and the time this packet was started. It's good for this number to be positive because a value of zero means the slo-scope might be sampling too slowly. The second byte is the low 8 bits of the USB frame number when the packet was started (basically a milli-second timer). If the SLO-scope is sampling fast enough and the computer is reading fast enough, then the USB frame number should increase by exactly one each time you read a new packet from the slo-scope, which should be every millisecond.

The format of the remaining 20 bytes depends on what state the slo-scope is in. For 10 kHz mode (SLOSCOPE_STATE_2ANALOG), the 3rd, 5th, 7th, etc bytes are 8-bit readings for Channel A while the 4th, 6th, 8th, etc bytes are 8-bit readings for Channel B. The readings are in the order they were taken. For 20 kHz mode (SLOSCOPE_STATE_1ANALOG_1DIGITAL), each of those 20 bytes contains a 7-bit reading of Channel A in the upper 7 bits, and a 1-bit reading of Channel B in the least significant bit.

Constants

 
#define REQUEST_GET_VARIABLE 0x81
#define REQUEST_SET_VARIABLE 0x82
 
#define VARIABLE_SLOSCOPE_STATE  0x42 // 1 byte
#define SLOSCOPE_STATE_OFF              0
#define SLOSCOPE_STATE_2ANALOG          1
#define SLOSCOPE_STATE_1ANALOG_1DIGITAL 2
 
#define VARIABLE_SLOSCOPE_PERIOD 0x40 // 2 bytes.  The slo-scope will take a new reading every (Period+1)/12 microseconds.  Default 539.
 
#define VARIABLE_FVR_ADC         0x41 // 2 bytes, read only.  A value of 1 indicates an error.  Otherwise it's a measurement of the 1.024 V internal voltage reference, as a number from 0 to 65472.
 
#define VARIABLE_SLOSCOPE_OUTPUT_STATE 0x43 // 2 bytes, first is line A and second is line B.
#define SLOSCOPE_OUTPUT_OFF       0
#define SLOSCOPE_OUTPUT_LOW       1
#define SLOSCOPE_OUTPUT_HIGH      3
#define SLOSCOPE_OUTPUT_NO_CHANGE 0xFF
 
#define REQUEST_GET_VARIABLE 0x81
/* To get the value of a variable from the device, make a request like this:
 *   bRequestType = 0b01000000  Direction=Device-to-host, Type=Vendor, Recipient=Device
 *   bRequest = REQUEST_GET_VARIABLE
 *   wValue = 0
 *   wIndex = The id of the variable (see VARIABLE_* defines below)
 *   wLength = [length of variable, in bytes]
 */
 
#define REQUEST_SET_VARIABLE 0x82
/* To set the value of a variable, make a request like this:
 *   bRequestType = 0b01000000  Direction=Device-to-host, Type=Vendor, Recipient=Device
 *   bRequest = REQUEST_GET_VARIABLE
 *   wValue = [value of variable]
 *   wIndex = The id of the variable (see VARIABLE_* defines below)
 *   wLength = 0
 */
 
enum variableIds
{
    VARIABLE_TARGET_VCC_ALLOWED_MINIMUM        = 0x01, // 1 byte, 
    VARIABLE_TARGET_VCC_ALLOWED_MAXIMUM_RANGE  = 0x02, // 1 byte, 
    VARIABLE_TARGET_VCC_MEASURED_MINIMUM       = 0x03, // 1 byte, read only
    VARIABLE_TARGET_VCC_MEASURED_MAXIMUM       = 0x04, // 1 byte, read only
    VARIABLE_PROGRAMMING_ERROR                 = 0x08, // 1 byte, read only
    VARIABLE_LINE_A_IDENTITY                   = 0x20, // 1 byte
    VARIABLE_LINE_B_IDENTITY                   = 0x21, // 1 byte
    // 0x40 - 0x4F are reserved for oscillsocope variables.  See oscilloscope_protocol.h
    VARIABLE_SW_MINOR                          = 0x90, // 1 byte
    VARIABLE_SW_MAJOR                          = 0x91, // 1 byte
    VARIABLE_HW_VER                            = 0x92, // 1 byte
    VARIABLE_SCK_DURATION                      = 0x98, // 1 byte
};
 
/* TARGET_VCC_UNITS is the conversion factor between all the TARGET_VCC variables above
 * and millivolts.  So (value in millivolts) = TARGET_VCC_UNITS * (value of VARIABLE_TARGET_VCC_MINIMUM).
 */
#define TARGET_VCC_UNITS 32
 
// LINE IDENTITY BYTES:
enum lineIds
{
    LINE_IS_NOTHING = 0x00, // Line is not used for anything.
    LINE_IS_DTR = 0x04, // DB9 Pin 4 - OUT - Data Terminal Ready
    LINE_IS_RTS = 0x07, // DB9 Pin 7 - OUT - Request to Send
    LINE_IS_CD  = 0x81, // DB9 Pin 1 - IN - Carrier Detect
    LINE_IS_DSR = 0x86, // DB9 Pin 6 - IN - Data Set Ready
    LINE_IS_RI  = 0x89, // DB9 Pin 9 - IN - Ring Indicator
};
 
#define REQUEST_START_BOOTLOADER 0xFF
/* To enter bootloading mode, send this request:
 *   bRequestType = 0b01000000  Direction=Host-to-device, Type=Vendor, Recipient=Device
 *   bRequest = REQUEST_START_BOOTLOADER
 *   wValue = 0
 *   wIndex = 0
 *   wLength = 0
 */
 
enum programmingErrors
{
    PROGRAMMING_ERROR_TARGET_VCC_BAD      = 0x01,
    PROGRAMMING_ERROR_SYNCH               = 0x02,
    PROGRAMMING_ERROR_IDLE_FOR_TOO_LONG   = 0x03,
    PROGRAMMING_ERROR_USB_NOT_CONFIGURED  = 0x04,
    PROGRAMMING_ERROR_USB_SUSPEND         = 0x05,
};

Control Transfers

bmRequestType bRequest wValue wIndex wLength Data
0xC0 REQUEST_GET_VARIABLE 0 VARIABLE_* 1 or 2 depending on variable value of variable
0x40 REQUEST_SET_VARIABLE value to store VARIABLE_* 0 none
0x40 REQUEST_START_BOOTLOADER 0 0 0 none

The programmer also responds to certain control transfers defined in the USB class specification document PSTN1.2, for setting the baud rate and the control line state of the two virtual COM ports: ACM_REQUEST_SET_CONTROL_LINE_STATE, ACM_REQUEST_GET_LINE_CODING, ACM_REQUEST_SET_LINE_CODING. Feel free to contact us for more information about using the serial ports. But there is already a driver in Linux that handles this stuff so you shouldn't need to worry about it.