Arcaze Feature Report Protocol

Introduction

This is the documentation of the low level feature report protocol of the Arcaze USB-Interface.

Please do only use this low level protocol, if you know why you’re doing it. When coding on a Windows platform, using the supplied Arcaze DLL is generally preferable, as it simplifies and harmonizes usage and also covers changes in the low level protocol. Changes are not overly common, but be aware that the feature report commands are subject to change (as opposed to the DLL functions).

The main reason to use this low level feature report protocol, would be platform independence, as currently there is no Arcaze DLL implementation for other platforms than MS Windows.

First experiences with the feature report protocol can be collected on the “Low Level Feature Reports” tab of the Arcaze DLL Demo:

Implementation

There are various libraries simplifiying the transfer of USB feature reports on different operating systems. Some of them will be shown here. Feel free to contribute your favorite API.

HIDAPI

The HIDAPI library is available for Windows, Linux, and Mac OS X based platforms. Documentation and download are available here: http://www.signal11.us/oss/hidapi/

Basic communication can be as simple as this (minus all error checking):

// Establish USB connection
handle = hid_open(0x1690, 0xfe13, NULL);

// Prepare out report data ("Read Ports" command)
buf[0] = 0x00;  
buf[1] = 0x08;

// Send out report
res = hid_send_feature_report(handle, buf, 65);

// Receive in report
res = hid_get_feature_report(handle, buf, sizeof(buf));

Command Reference

All command IDs are noted in decimal.

Multiple Byte values are transmitted with lowest byte first (“Litte Endian” / “LSB first”).

Memory Access Commands

These commands are used to write a new configuration to the Arcaze USB-Interface.
 

CommandIDDescription
ReadRam2Read TransferRAM contents from Arcaze
WriteToRam3Write TransferRAM contents in Arcaze
CopyFlashToRam4Copy Flash contents to TransferRAM
ClearFlash5Erase a flash sector
ProgRamToFlash6Program Flash sector from TransferRAM
ClearRam7Clear TransferRAM contents

System Commands

CommandIDDescription
ValidateConfig12Validate a configuration after copying it to flash.
InvalidateConfig13Invalidate a configuration. Arcaze will not use it anymore.
ReadStatus17Reads status of configuration (valid / invalid)
ReadConfigNumber18Reads ID of the currently active configuration
StartMacros21Start execution of all macros in configuration
StopMacros22Stop execution of all macros in configuration
SetConfig28Activates a specific configuration
Reset252Soft-Resets the whole Arcaze USB-Interface
ReadBootSerialNumber253Reads base serial number of the USB-Interface
Enumerate254Resets the USB bus only / Re-Enumerates
InvalidateFirmware255Invalidates the firmware. Firmware update will be mandatory after this command!

Onboard Port Commands

CommandIDDescription
ReadPorts8 
ReadADC27 
SetPinDirection29 
SetPin30 
SetPortDirection31 
SetPort32 
ReadQuadratureEncoders44 
ReadPortsWithHistory45 

Display Driver Commands

CommandIDDescription
CmdIdMax7219DisplayInit33 
CmdIdMax7219WriteReg34 
CmdIdMax7219ReadReg35 
CmdIdMax7219WriteDigits36 

LED Driver 2 Commands

CommandIDDescription
CmdIdTlc5926Init37 
CmdIdTlc5926WriteLeds38 
CmdIdTlc5926StrobeEnable39 

LED Driver 3 Commands

CommandIDDescription
CmdIdTlc5943Init40 
CmdIdTlc5943WriteLeds1Bit41 
CmdIdTlc5943WriteLeds8Bit42 
CmdIdTlc5943Strobe43 

Command Descriptions

Feature Report Length & Report ID

All in and out feature reports are 64 bytes long, without any exception. Do not send a different number of bytes.

But be aware of the Feature Report ID. On MS Windows based systems, this ID normally is simply prefixed to the actual feature report data. Therefore the feature report data actually sent/received is one byte longer than described in the command descriptions below, which don’t include it, as it’s not part of the protocol.

Currently we are not using the USB Feature Report IDs, therefore this byte is always 0x00.

To conclude:

  • If your USB stack requires the Report ID to be included with the report data, always send 65 bytes. First byte is 0x00 and Command starts at second byte.
  • Otherwise send and receive 64 bytes.

Status Return Values

Many commands return a status value. This can be one of the following values:

NameValue
STATUS_SUCCESS0
STATUS_WRITE_OUTSIDE_RAM1
STATUS_READ_OUTSIDE_RAM2
STATUS_WRONG_SECTOR3
STATUS_FLASH_FAILURE4
STATUS_COMMAND_NOT_IMPLEMENTED5
STATUS_WRONG_HASH6
STATUS_INVALID_PORT_NUMBER7

Memory Access Commands

READ_RAM (2)

Read Data from the TransferRAM. This is mainly used together with CMD_COPY_FLASH_TO_RAM.

The Out Feature Report sets the base address of the data to be read. With every In Feature Report the base address is incremented by the number of received bytes. Therefore it’s also possible to do “burst reads” with one Out Report, setting the start address and multiple In Reports to read the data continuously.

Out Report
AddressContentValueLength
(Bytes)
Remarks
0Command21 CMD_READ_RAM
1Address 2 Start address for read. This is the relative address inside the TransferRAM, first byte has address 0.
3…63Not used  Not used

No length is submitted. The In report is always completely filled until the end of the RAM block is reached or the internal number of valid bytes is reached.

In Report 
AddressContentValueLength
(Bytes)
Remarks
0Command21CMD_READ_TRANSFER_RAM
1Status 1Status Return Value
2Address 2Base address of Data
4Length 1Number of valid bytes in this report
5…63Payload 58Payload data

In reports can be polled until end of RAM block is reached (address 0x0fff). Continued reads supply all zeros.

Additionally note that the firmware also respects the number of valid bytes in RAM. So, if by a previous command only the first 256 bytes have been written, it’s not possible to read above address 0x00ff. When reading above, the data is all zero.

WRITE_RAM (3)

Write Data to TransferRAM.

This Out Feature Report can write a maximum of 58 bytes into TransferRAM. Every Out Feature Report sets the destination address, therefore there is no burst mode here.

Important: Note that you have to issue a CMD_CLEAR_FLASH_RAM before being able to write to Flash RAM for security reasons!

Out Report
AddressContentValueLength (Bytes)Remarks
0Command31CMD_WRITE_RAM
1Address 2Start address for write. This is the relative address inside the Flash RAM, first byte has address 0.
3Length 1Number of bytes to write in this report.
4…61Payload 58Payload (maximum size is 58 bytes!)

It’s possible to write to any address between 0x0000 and 0x0fff. All other writes are ignored and an RETVAL_WRITE_OUTSIDE_RAM error is issued.

COPY_FLASH_TO_RAM (4)

Copies addressed data from a flash sector to the TransferRAM.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command41CMD_COPY_FLASH_TO_RAM
1SectorID 1Sector ID to be read. Refer to sector table.
2…63Not used  Not used

CLEAR_FLASH (5)

Erase a flash sector.

Access restrictions apply. If a user is not entitled to erase this sector it is denied. Refer to flash sector table to see which sectors allow erasing.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command51 CMD_CLEAR_FLASH
1SectorID 1 Sector ID to be erased. Refer to sector table.
2…63Not used   Not used

COPY_RAM_TO_FLASH (6)

Programs Transfer RAM contents into Flash Memory.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command0d61CMD_COPY_RAM_TO_FLASH
1SectorID 1SectorID 
3…63   Not used
In  Report
AddressContentValueLength (Bytes)Remarks
0Command61 CMD_COPY_RAM_TO_FLASH
1Return Value 1 Return Value refer to table of status return values

CLEAR_RAM (7)

Clears the complete TransferRAM (4kBytes total) by overwriting all bytes with 0xFF.

Important: Note that you have to issue a CMD_CLEAR_RAM before being allowed to write to TransferRAM for security reasons! The number of valid data bytes in TransferRAM is set to 0x1000 by this command, so all data bytes can be read and overwritten afterwards.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command71 CMD_CLEAR_RAM
1…63    Not used

System Commands

TBD

Onboard Port Commands

READ_PORTS (8)

Reads states of internal digital ports.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command81CMD_ID_READ_PORTS
1…63   Not used
In  Report
AddressContentValueLength (Bytes)Remarks
0Command81CMD_ID_READ_PORTS
1Status01STATUS_SUCCESS
2Reservedx1Reserved (was LastChanged, but currently not implemented)
3Port A1 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
4Port A2 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
5Port A3 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
6Port A4 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
7Port A5 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
8Port A6 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
9Port A7 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
10Port A8 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
11Port A9 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
12Port A10 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
13Port A11 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
14Port A12 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
15Port A13 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
16Port A14 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
17Port A15 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
18Port A16 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
19Port A17 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
20Port A18 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
21Port A19 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
22Port A20 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
23Port B1 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
24Port B2 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
25Port B3 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
26Port B4 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
27Port B5 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
28Port B6 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
29Port B7 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
30Port B8 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
31Port B9 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
32Port B10 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
33Port B11 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
34Port B12 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
35Port B13 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
36Port B14 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
37Port B15 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
38Port B16 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
39Port B17 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
40Port B18 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
41Port B19 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
42Port B20 value0 or 11Actually only Bit 0 is used. Bits 1…7 are always 1
43…63not used0 not used

CMD_READ_ADC (27)

Reads ADC values of the 6 internal ADCs. Item size is 16 bits, but in Arcaze USB-Interface V3 only 10 bits are used. In Arcaze USB-Interface V4, 12 bits are used.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command271CMD_READ_ADC
1…63   Not used
In  Report
AddressContentValueLength (Bytes)Remarks
0Command271CMD_READ_ADC
1Status 1 
2ADC port 0 (AIN 1) value (LSB first) 2 
4ADC port 1 (AIN 2) value (LSB first) 2 
6ADC port 2 (AIN 3) value (LSB first) 2 
8ADC port 3 (AIN 4) value (LSB first) 2 
10ADC port 4 (AIN 5) value (LSB first) 2 
12ADC port 5 (AIN 6) value (LSB first) 2 
14…63not used   

SET_PIN_DIRECTION (29)

Sets I/O direction of a single onboard I/O pin.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command291CMD_SET_PIN_DIRECTION
1NumPin0…391Number of onboard pin. 0…19=Port A, 20…39=Port B
2Direction0 or 110=Input / 1=Output
3…63not used  Not used

SET_PIN (30)

Sets output level of a single onboard I/O pin.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command301CMD_SET_PIN
1NumPin0…391Number of onboard pin. 0…19=Port A, 20…39=Port B
2Value0 or 110=Low / 1=High
3…63not used  Not used

Physically 0 means low = 0V and 1 means high = 3.3V.

SET_PORT_DIRECTION (31)

Sets pin directions of all pins of a complete onboard I/O port (A or B). All 20 pins directions of the selected port are being overwritten.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command311CMD_SET_PORT_DIRECTION
1NumPort0…11Number of onboard port 0=Port A, 1=Port B
2Directions0…0xfffff4Bitmask:
Bit 0 = pin 0 of selected port, bit 19= pin 19 of selected port.
Bit value 0=input / bit value 1=output
6…63not used  Not used

SET_PORT (32)

Sets pin output values of all pins of a complete onboard I/O port (A or B). All 20 pins output values of the selected port are being overwritten.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command321CMD_SET_PORT
1NumPort0…11Number of onboard port 0=Port A, 1=Port B
2Values0…0x000fffff4Bitmask:
Bit 0 = pin 0 of selected port, bit 19= pin 19 of selected port.
Bit value 0=output low / bit value 1=output high
6Action0=on
1=off
2= set
1 Selects how the port values are used:
– On means that for each 1-bit in the port values mask a pin is being set to high and the others are not touched.
– Off means that for each 1-bit in the port values mask a pin is being set to low and the others are not touched.
– Set meand that all values are copied 1:1 to the ports. 1’s become output highs and 0’s become lows. No pins of the addressed port stay untouched.
7…63not used  Not used

READ_QUADRATURE_ENCODERS (44)

Read quadrature encoder values.

Quadrature encoders can be connected to each neighbouring pair of pins like A1/2, A3/4, … , B37/39, B39/40. So, total of 20 quadrature encoders can be connected. Each of these quadrature encoders is represented by a 16 bit signed integer value in this in report. It counts up when turned to one direction and counts down when turned to the other direction. It overflows from -32768 to 32767 and vice versa.

The values are not being reset at any time. To follow the rotation of a quadrature encoder, the value has to sampled twice and the difference between the values represents the number of pulses, the encoder has been rotated in the meantime.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command441CMD_READ_QUADRATURE_ENCODERS
1…63not used  Not used
In  Report
AddressContentValueLength (Bytes)Remarks
0Command0d1CMD_READ_QUADRATURE_ENCODERS
1Status Return Value01SUCCESS
2EncoderValues-32768…3276740 (2 bytes each)Quadrature encoder counter values 0…19
     

READ_PORTS_WITH_HISTORY (45)

This is a more sophisticated version of the READ_PORTS command.

In addition to the current state of each onboard I/O pin, it also returns the number of changes each pin has experienced since the last READ_PORTS_WITH_HISTORY command. This can be helpful to find out, if any changes on a port have been missed since reading the port last time. Reasons may be insufficient polling frequency or bouncing of a switch for example.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command451READ_PORTS_WITH_HISTORY
1…63not used  Not used
In  Report
AddressContentValueLength (Bytes)Remarks
0Command451READ_PORTS_WITH_HISTORY
1Status Return Value01SUCCESS
2LastChanged0…40 0: no changes since last call
1…20: Last change was on Port A1…A20
21…40: Last change was on Port B1…B20
3InputDatabitmask20 (1 byte per pin)Bit 0: Current State of this Pin
Bit 1..7: Number of changes on this pin since last call of READ_PORTS_WITH_HISTORY
4…63not used   

The last changed value shows, which pin has changed last. In some situations it saves time to know this immediately.

Display Driver Commands

Display Driver Basics

The Display Driver modules are extension modules, connected to the extension port of the Arcaze-USB Interface.

Display Driver Types

Currently 2 different Display Driver Modules exist:

Display Driver 1
  • This module contains only one display driver chip and therefore can drive 8 digits in total.
  • The bus address can be set by a rotary switch to values 0 to 15.
  • Theoretically up to 16 Display Driver 1 modules could be connected to an Arcaze USB-Interface.
  • The Display Driver 1 is obsolete.
Display Driver 32
  • This module contains 4 display driver chips and therefore can drive 32 digits in total.
  • The bus address can be set by solder bridge SB101. When set to “1” or open, the bus addresses of the display driver chips are 0…3. When set to “2”, the bus addresses of the display driver chips are 4…7.
  • 1 or 2 Display Driver 32 modules can be connected to an Arcaze USB-Interface.
Decode Mode

There are 2 different ways to display data sent to a display driver. The “Decode Mode” can be set up on a per-digit basis.

Decode Mode = 0 / Bitmapped Mode

If a digit is set up for deocde mode 0, the data is displayed as a bitmap exactly as it has been received. So each bit of a byte stands for one segment of a digit as shown here:

Decode Mode = 1 / Code B Decoding

If decode mode 1 is selected for a digit, a small character generator is used and only bits 0…3 of display data are interpreted and displayed as shown in the table below. Additionally bit 7 represents the DP point.

MAX7219_DISPLAY_INIT (33)

Initializes a display driver chip of a Display Driver Module connected to the extension port of the Arcaze USB-Interface.

A Display Driver 1 module contains only one display driver. Therefore, only one Init command is required per module. The Display Driver 32 module contains 4 display drivers, each with its own address. Therefore it’s necessary to send the init command 4 times, once to each address. This has not been combined into one command to allow for setting brightness or other settings different for each chip if desired.

Out Report
AddressContentValueLength (Bytes)Remarks
0Command331MAX7219_DISPLAY_INIT
1Device Address0…71Bus address of the display driver chip.
On a Display Driver 32 this can be 0..3 for the first module and 4…7 for the second module connected to the Arcaze USB-Interface.
On a Display Driver 1 this can be 0…15, which is the address to be set by the rotary switch on each Display Driver 1 module.
2Decode ModeBitmask1Each bit reflects one digit.
If a bit is set to 0, display data is not decoded, but simply displayed as a bitmap for all segments of this digit.
If a bit is set to 1, display data is decoded and displayed as Code B font, as shown in the Code B font table earlier.
3Intensity0…1510 = darkest, 15 = brightest
4ScanLimit4…81Selects the number of digits to actually be updated from a display driver. This can generally be left at value 8.
The only reason to alter this value, would be to achieve a higher frame update rate on a display smaller than 8 digits, as scanning becomes the faster, the less digits are to be updated. But this will only be relevant in very specific applications (like moving displays).
5…63not used  not used

The last changed value shows, which pin has changed last. In some situations it saves time to know this immediately.

MAX7219_WRITE_DIGITS (36)

Out Report
AddressContentValueLength (Bytes)Remarks
0Command361MAX7219_WRITE_DIGITS
1Device Address0…71Bus address of the display driver chip.
On a Display Driver 32 this can be 0..3 for the first module and 4…7 for the second module connected to the Arcaze USB-Interface.
On a Display Driver 1 this can be 0…15, which is the address to be set by the rotary switch on each Display Driver 1 module.
2Digit 0 Data0x00…0xff1Display Data goes here. Can be bitmapped or Code B.
Digit 0 is on the right side for displays attached to connector A and on the left side for displays attached to connector B
3Digit 1 Data0x00…0xff1Display Data for digit 1 goes here. Can be bitmapped or Code B.
4Digit 2 Data0x00…0xff1Display Data for digit 2 goes here. Can be bitmapped or Code B.
5Digit 3 Data0x00…0xff1Display Data for digit 3 goes here. Can be bitmapped or Code B.
6Digit 4 Data0x00…0xff1Display Data for digit 4 goes here. Can be bitmapped or Code B.
7Digit 5 Data0x00…0xff1Display Data for digit 5 goes here. Can be bitmapped or Code B.
8Digit 6 Data0x00…0xff1Display Data for digit 6 goes here. Can be bitmapped or Code B.
9Digit 7 Data0x00…0xff1Display Data for digit 7 goes here. Can be bitmapped or Code B.
Digit 7 is on the left side for displays attached to connector A and on the right side for displays attached to connector B
10DigitsMask0x00…0xff1Bit 0 = Digit 0 … Bit 7 = Digit 7
11…63not used  not used
Example Command
00
24 00 01 02 03 04 05 06 07 08 0f 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Results:

  • Accesses display driver on bus address 0
  • Writes 1 to digit 0
  • Writes 2 to digit 1
  • Writes 3 to digit 2
  • Writes 4 to digit 3
  • Does not change contents of digits 4 to 7, because their bits are set to 0 in the DigitsMask register!