HackerPort USB message specification
version 0.6 date 2005-06-08
part of the hacker port project - http[s]://1stein.schuermans.info/hackerport/
Copyright (C) 2003-2005 Stefan Schuermans <1stein@schuermans.info>
Copyleft: GNU public license - http://www.gnu.org/copyleft/gpl.html



PC -> HackerPort
----------------

commands are sent using messages on bulk output endpoints 1, 2 and 3

the first packet is sent on endpoint 1, the second one on endpoint 2,
the third one on endpoint 3, the fourth one on endpoint 1, and so on

this enables the PC to send 3 packets until it receives a NAK
due to a filled FIFO in the USBN9604

for synchronizing purposes, the first byte in every packet
is a sequence number incrementing with each packet

multiple command messages may be combined into a single packet of length <= 64

0x00 <data>
  set output port A
0x01 <data>
  set output port B
0x02 <data A> <data B>
  set output ports A and B
0x04
  read input port A
0x05
  read input port B
0x06
  read input ports A and B
0x08 <data 0> ... <data 15>
  burst output on output port A
0x09 <data 0> ... <data 15>
  burst output on output port B
0x0A <data A 0> <data B 0> ... <data A 15> <data B 15>
  burst output on output ports A and B
0x0C <data 0> ... <data 15>
  burst output on output port A combined with input on input port A
  (after each byte is output, a byte is input)
0x0D <data 0> ... <data 15>
  burst output on output port B combined with input on input port B
  (after each byte is output, a byte is input)
0x0E <data A 0> <data B 0> ... <data A 15> <data B 15>
  burst output on output ports A and B combined with input on input port A and B
  (after each byte is output, a byte is input)

0x10 <data_h> <data_l>
  set PWM output A
0x11 <data_h> <data_l>
  set PWM output B
0x12 <data_h A> <data_l A> <data_h B> <data_l B>
  set PWM outputs A and B
0x13 <speed>
  set PWM speed (i.e. frequency)
  speed: frequency in 250 Hz steps

0x18
  read analog input A
0x19
  read analog input B
0x1A
  read analog input C
0x1B
  read analog input D
0x1C
  read analog input E
0x1D
  read analog inputs A ... E

0x20 <bit_time_h> <bit_time_l>
  set baudrate
  bit_time: time for a single bit (in 100 ns steps)
0x21 <byte>
  send a byte using the serial port

0x30 <bit_time>
  set i2c bus speed
  bit_time: time for a single bit (in 100 ns steps)
0x31
  output a start condition to the i2c bus
0x32 <byte>
  write a byte to the i2c bus and get acknowledge
0x33
  read a byte from the i2c bus
0x34
  output an acknowledge to the i2c bus
0x35
  output a not-acknowledge to the i2c bus
0x36
  output a stop condition to the i2c bus

0x40 <state>
  set pins of PIC programmer
  state.D1-D0: 00: no change
               01: VPP output to "0V"
               10: VPP output to "13V"
               11: VPP output to "open"
  state.D3-D2: 00: no change
               01: PGC output to "low"
               10: PGC output to "high"
               11: no change
  state.D5-D4: 00: no change
               01: PGD output to "low"
               10: PGD output to "high"
               11: PGD output to "open"
  state.D7-D6: reserved, 00
0x41
  read PGD input of PIC programmer
0x42 <count> <data_h> <data_l>
  shift out <count> bits to PIC, LSB first
  count is clamped to be <= 0x10, data must be aligned right
  actions: set PGC "low", set PGD "low", (set PGC "high", PGD <- next bit, set PGC "low"){count}
0x43 <count>
  shift in <count> bits from PIC, LSB first
  count is clamped to be <= 0x10
  actions: set PGC "low", set PGD "open", (set PGC "high", next bit <- PGD, set PGC "low"){count}

0x50 <state>
  set pins of JTAG master port
  state.D1-D0: 00: no change
               01: NTRST output to "low"
               10: NTRST output to "high"
               11: no change
  state.D3-D2: 00: no change
               01: TMS output to "low"
               10: TMS output to "high"
               11: no change
  state.D5-D4: 00: no change
               01: TCK output to "low"
               10: TCK output to "high"
               11: no change
  state.D7-D6: 00: no change
               01: TDI output to "low"
               10: TDI output to "high"
               11: no change
0x51
  read TDO input of JTAG master port

0xF0
  get ID of this hacker port
0xF1 <ID0> <ID1> ... <ID15>
  set ID of this hacker port

0xFF
  read version information

HackerPort -> PC
----------------

answers are received using messages on bulk input endpoints 1, 2 and 3

the first packet is sent on endpoint 1, the second one on endpoint 2,
the third one on endpoint 3, the fourth one on endpoint 1, and so on

this enables the PC to fetch 3 packets until it receives a NAK
due to an empty FIFO in the USBN9604

for synchronizing purposes, the first byte in every packet
is a sequence number incrementing with each packet

multiple answer messages may be combined into a single packet of length <= 64

0x00
  output port A set
0x01
  output port B set
0x02
  output ports A and B set
0x04 <data>
  input port A read
0x05 <data>
  input port B read
0x06 <data A> <data B>
  input ports A and B read
0x08
  burst output on output port A done
0x09
  burst output on output port B done
0x0A
  burst output on output ports A and B done
0x0C <data 0> ... <data 15>
  data read from input port A during burst output/input
0x0D <data 0> ... <data 15>
  data read from input port B during burst output/input
0x0E <data A 0> <data B 0> ... <data A 15> <data B 15>
  data read from input ports A and B during burst output/input

0x10
  PWM output A set
0x11
  PWM output B set
0x12
  PWM outputs A and B set
0x13 <speed>
  PWM speed (i.e. frequency) has been set
  speed: frequency in 250 Hz steps

0x18 <data_h> <data_l>
  analog input A read
0x19 <data_h> <data_l>
  analog input B read
0x1A <data_h> <data_l>
  analog input C read
0x1B <data_h> <data_l>
  analog input D read
0x1C <data_h> <data_l>
  analog input E read
0x1D <data_h A> <data_l A> ... <data_h E> <data_l E>
  analog inputs A ... E read

0x22 <byte>
  received a byte on the serial port
0x23 <error>
  error occured on serial port
  error: 0x01=framing error
         0x02=overflow error (in hardware)
	 0x04=buffer overflow error

0x30 <bit_time>
  i2c bus speed has been set
  bit_time: time for a single bit (in 100 ns steps)
0x31
  start condition has been output to the i2c bus
0x32 <ack>
  a byte has been written to the i2c bus and an acknowledge bit was read
  ack: 0=not-acknowlegded, 1=acknowledged
0x33 <byte>
  a byte has been read from the i2c bus
0x34
  acknowledge has been output to the i2c bus
0x35
  not-acknowledge has been output to the i2c bus
0x36
  stop condition has been output to the i2c bus


0x40
  pins of PIC programmer set
0x41 <value>
  PGD input of PIC programmer read
  value == 0x00: input is "low"
  value == 0x01: input is "high"
0x42 <count>
  <count> bits have been shifted out to PIC, LSB first
0x43 <count> <data_h> <data_l>
  <count> bits shifted in from from PIC, LSB first
  data is aligned right

0x50
  pins of JTAG master port set
0x51 <value>
  TDO input of JTAG master port read
  value == 0x00: input is "low"
  value == 0x01: input is "high"

0xF0 <ID0> <ID1> ... <ID15>
  ID of this hacker port
0xF1 <error>
  error == 0x00: ID of hacker port was set
  error != 0x00: ID of hacker port could not be set

0xFF <variant> <major> <minor> <revision> <year_h> <year_l> <month> <day>
  version information read
  (<variant> specifies the hardware variant of the hacker port:
             0x00: original hacker port with PIC18F442 and USBN9604)