Flexiband API

USB Interface

USB Descriptors

The Flexiband USB3.0 device has one Configuration with one Interface. This Interface has three AlternateSettings for different transfer rates. The Interface always has the same Isochronous Endpoint, but with different reserved bandwith.

Endpoints are used to communicate with USB devices. See USB Functions. All USB devices have the Endpoint EP0 for Control Transfers. These Control Transfers can be used for Standard Device Requests and for Vendor Requests. Control Transfers have a limited payload size and are only used to change settings or request status.

The Flexiband also has the Endpoint EP3 for Isochronous Transfers. This Endpoint starts to produce data as soon as the Flexiband was started with the "Start data transfer" Vendor Request (see below). For the data format see Data Format.

USB Vendor Requests

FX3-USB-Controller

Get Interface-Board Revision

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x00	0x00	-	0x01	Board Revision (1 byte)

Since FX3 build: 3
Since Atmel build: -

Get FX3 Infos

• Jenkins Build Number
• First eight hex characters of git hash.
• Build time in seconds since 01.01.2000.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x00	0x01	-	0x02	Build Number (2 byte)
0xC0	0x00	0x02	-	0x04	Git Hash (4 byte)
0xC0	0x00	0x03	-	0x04	Timestamp (4 byte)

Since FX3 build: 3
Since Atmel build: -

Start/Stop data transfer

• Yellow LED on Flexiband switched on/off.
• Start=0; Stop=1

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x40	0x00	<start/stop>	-	0x00	-

Since FX3 build: 3
Since Atmel build: -

Power on/off Base-Board

• on=2; off=3

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x40	0x00	<on/off>	-	0x00	-

Since FX3 build: 3
Since Atmel build: -

Load FPGA

Load a bitstream into the FPGA. The bitstream has to be loaded page by page. Page loading is started by transferring the first page. Each page is 512 bytes. Increment the page counter with every transfer. For the last page, issue a vendor request with wIndex=0xffff to finalize the upload.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x40	0x00	0xff00	<page>	<len>	Data (512 byte)
0x40	0x00	0xff00	0xffff	0	-

Hard reset

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x40	0x00	0xffff	-	0x00	-

Since FX3 build: 16
Since Atmel build: -

Atmel

Get/Set AutoGainControl

• off=0; on=1

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x01	-	0x20	0x01	<on/off>
0x40	0x01	<on/off>	0x20	0x00	-

Since FX3 build: 3
Since Atmel build: 25

Get Base-Board Revision

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x02	0x00	-	0x01	Board Revision (1 byte)

Since FX3 build: 3
Since Atmel build: 9

Get Atmel Info

• Jenkins Build Number.
• First eight hex characters of git hash.
• Build time in seconds since 01.01.2000.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x02	0x01	-	0x02	Build Number (2 byte)
0xC0	0x02	0x02	-	0x04	Git Hash (4 byte)
0xC0	0x02	0x03	-	0x04	Timestamp (4 byte)

Since FX3 build: 3
Since Atmel build: 7

Base-Board / FPGA

Get FPGA Info

• Jenkins Build Number.
• First eight hex characters of git hash.
• Build time in seconds since 01.01.2000.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x03	0x01	-	0x02	Build Number (2 byte)
0xC0	0x03	0x02	-	0x04	Git Hash (4 byte)
0xC0	0x03	0x03	-	0x04	Timestamp (4 byte)

RF-Boards

<RF-Slot>: 0 - 2
This documents describes Layout ID=1

Get RF-EEPROM Layout

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x00	<RF-Slot>	0x01	Layout ID (1 byte)

Since FX3 build: 3
Since Atmel build: 7

Get RF-Board Serial

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x01	<RF-Slot>	0x01	Board Serial (1 byte)

Since FX3 build: 3
Since Atmel build: 7

Get RF-Board Antenna Number

Antenna Number on Flexiband Housing: 1 - 3

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x02	<RF-Slot>	0x01	Antenna Number (1 byte)

Since FX3 build: 3
Since Atmel build: 7

Get RF-Board RF-Bandwidth

Analog filter bandwidth in MHz.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x03	<RF-Slot>	0x01	Bandwidth (1 byte)

Since FX3 build: 3
Since Atmel build: 7

Get RF-Board Lo Freq

Local oszillator freq in Hz.

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x04	<RF-Slot>	0x04	LO frequency (4 byte)

Since FX3 build: 3
Since Atmel build: 7

Get RF-Board Band Name

Human readable name; ASCII (i.e. L1/G1).

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x08	<RF-Slot>	0x08	Name (8 byte)

Since FX3 build: 3
Since Atmel build: 7

Get RF-Board DAC Info

Minimum, maximum meaningful values and default value for the DAC (see below).

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x10	<RF-Slot>	0x01	DAC min (1 byte)
0xC0	0x04	0x11	<RF-Slot>	0x01	DAC max (1 byte)
0xC0	0x04	0x12	<RF-Slot>	0x01	DAC default (1 byte)

Since FX3 build: 3
Since Atmel build: 7

Get/Set RF-Board Antenna Supply default

The default value is applied on startup.

• Rev1 on: 0xFF – off: 0xFD
• Rev2 on: 0xFD – off: 0xFF

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x04	0x13	<RF-Slot>	0x01	Ant power default (1 byte)
0x40	0x04	0x13	<RF-Slot>	0x01	Ant power default (1 byte)

Set RF-Board Antenna Supply

• Rev1 on: 0xFF – off: 0xFD
• Rev2 on: 0xFD – off: 0xFF

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x40	0x05	<on/off>	<RF-Slot>	0x00	-

Get RF-Board Info

• Bit0: Antenna Fault
• Bit1: Antenna Supply
• Bit2-3: Board Revision (zero based, so add one to get the actual revision)

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0xC0	0x05	0x00	<RF-Slot>	0x01	Status (2 bit) + Revision (2 bit)

Set RF-Board Amplification

• <amp>: 0 (min amplification) – 255 (max amplification)
• Should be between DAC min and DAC max, see Get RF-Board DAC Info
• TODO: Amplification in dB (0 – 70)

bmRequestType	bRequest	wValue	wIndex	wLength	Data
0x40	0x06	<amp>	<RF-Slot>	0x00	-

Since FX3 build: 3
Since Atmel build: 14

Data Format

Framing

Data frames are always 1024 bytes long. They contain a preamble, a 32-bit counter, payload data and padding to fill up the frame.

The counter starts at zero when the flexiband is started with the "Start data transfer" Vendor Request. It increments with each frame. When the maximum value is reached is rolls over to zero.

The padding is currently filled with 0x00 bytes. In a later version it might be used as CRC.

0	1	2	3	4	5	6	7	...	m	...	1023
PREAMBLE		COUNTER				PAYLOAD DATA			PADDING
0x55	0xAA	count				(up to 1014 bytes)			0x00

Payload

The layout of the payload depends on the current FPGA configuration. Here are some examples:

byte	0				1				...	1013
I-3	L5 I [7:4]		L5 Q [3:0]		L5 I [7:4]		L5 Q [3:0]		...	L5 I [7:4]		L5 Q [3:0]
III-1a	L2 I [7:6]	L2 Q [5:4]	L1 I [3:2]	L1 Q [1:0]	L5 I [7:4]		L5 Q [3:0]		...	L5 I [7:4]		L5 Q [3:0]

byte	0				1				2				3				...	1011
III-1b	L2 I [7:4]		L2 Q [3:0]		L1 I [7:4]		L1 Q [3:0]		L5 I [7:4]		L5 Q [3:0]		L5 I [7:4]		L5 Q [3:0]		...	L5 I [7:4]		L5 Q [3:0]