flfire/fire_protocol.org

# Creator note:
# Working on this is pointless without the device to test on...

* AKAI FLStudio Fire USB protocol
All values are in HEX unless annotated otherwise. \\
The FIRE uses bulk transfers
on the endpoint 81 (IN) and 1 (OUT).

** Fire to host (IN)
*** Action header
A action header consists of two bytes the first of which we call the action.
The second byte is identical to the first byte but with the nibbles swapped. \\
Example: action: =0b=, header: =0bb0=

The protocol looks somewhat like MIDI.

*** Nob bytes
action: =0b= \\
data: =<knob><direction>= \\

| <l>  |           |
| byte | knob      |
|------+-----------|
| 10   | volume    |
| 11   | pan       |
| 12   | filter    |
| 13   | resonance |

| <l>  |           |
| byte | direction |
|------+-----------|
| 01   | cw        |
| 7f   | ccw       |

*** Button bytes <press / release>
action: =09= / =08= \\
data: =<button><something>= \\

| <l>  |               |
| byte | button        |
|------+---------------|
| 10   | volume        |
| 11   | pan           |
| 12   | filter        |
| 13   | resonance     |
| 19   | select button |
| 1a   | mode switch   |
| 1f   | pattern up    |
| 20   | pattern down  |
| 21   | browser       |
| 22   | grid left     |
| 23   | grid right    |
| 24   | mute 1        |
| 25   | mute 2        |
| 26   | mute 3        |
| 27   | mute 4        |
| 2c   | step          |
| 2d   | note          |
| 2e   | drum          |
| 2f   | perform       |
| 30   | shift         |
| 31   | alt           |
| 32   | pattern/song  |
| 33   | PLAY          |
| 34   | STOP          |
| 35   | RECORD        |
row values: each row 16 values, top left is 36, next one 46, etc.

| <l>  |                        |
| byte | something              |
|------+------------------------|
| 00   | release non row button |
| 20   | release row button     |
| 7f   | press button           |

** Host to Fire (OUT)
*** Action header
/Same as above/

*** Set LED
action: =0b= \\
data: =<led><value>= \\

| <l>   |                   |
| byte  | LED               |
|-------+-------------------|
| 1b 11 | channel led       |
| 1b 12 | mixer             |
| 1b 14 | user 1            |
| 1b 18 | user 2            |
| 28    | mute 1 square led |
| 29    | mute 2 square led |
| 2a    | mute 3 square led |
| 2b    | mute 4 square led |
| 7f    | whole board       |
Other values correspond to the button bytes.

| <l>  |                 |
| byte | value           |
|------+-----------------|
| 00   | off             |
| 02   | common on value |

*** Set pad LED
header: \\
=0x04 0xf0 0x47 0x7f 0x04 0x43 0x65 0x00= \\
data: \\
=0x04 0x04 PAD_ID R 0x07 G B 0xf7=

*** Write a screen buffer
header: \\
=0x04 0xf0 0x47 0x7f 0x04 0x43 <writemode> <high 7 bits length>= \\
=0x04 <low 7 bits length> [ystart (pixels / 8)] [yend + 1 (pixels / 8)] 0x04 xstart [xend + 1] <byte>= \\
data: =[0x04 <3 bytes>]+ 0x07 <2 bytes> 0xf7=

| byte          | writemode        | observations with continous 0b1010101 |
|---------------+------------------+---------------------------------------|
| 0x0e          | 8 pixels height  | near checkerboard pattern             |
| 0x0d and 0x0f | 7 pixels height? | straight lines                        |



Pixels are writen from bottom to top in a 8 pixel high and =width= pixel wide grid. \\
For $yend - ystart > 0$ the grid wraps around horizontally to the next 8 pixels under the written ones. \\
Example: For bytes a to p with $xend - xstart = 7$ and $yend - ystart = 1$ the buffer will be written in this order. \\
*Simplification as seen below.*
#+BEGIN_EXAMPLE
abcdefgh
ijklmnop
#+END_EXAMPLE

The buffer must substitute one =04= action with a =0f= action,
the pupose of this is unknown (validation?) and thus it is currently recommended
to put it right after the header.
To note is that only the first byte of the =0f= action is rendered to the screen,
thus for a byte sequence =0 1 2 3 5 6 7= the transfered sequence should look like this:
#+BEGIN_EXAMPLE
04 00 01 02 0f 03 00 00 04 05 06 07
#+END_EXAMPLE

The pixels written are the least significant 7 bits of a data byte, \\
they are written from most significant to least significant bit. \\
Example: With the two bytes =(0 1 2 3 4 5 6 7)= and =(8 9 a b c d e f)= the following pixels are put on screen:
#+BEGIN_EXAMPLE
9
7
6f
5e
4d
3c
2b
1a
#+END_EXAMPLE

Notes:
- The data written can be longer or shorter than the defined box, \\
  this will result in part of the buffer being dropped or a part of the box staying unchanged.

*** Clear parts of the screen
header:
=0x04 0xf0 0x47 0x7f 0x04 0x43 0x08 0x00= \\
=0x04 0x03 0x00 0x00 0x06 <row> 0xf7 0x00=

Notes:
- The first byte of the termination sequence is 06 instead of the usual 07
* Hardware
** Screen
128x64 black and white OLED screen