User Tools

Site Tools


x0x:serialprotocol

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

x0x:serialprotocol [2016/01/28 18:05] (current)
Line 1: Line 1:
 +===== SERIAL PROTOCOL =====
 +
 +A serial packet between the x0xb0x and the c0ntr0l ​
 +application is composed of the following parts:
 +
 +== Header==
 +  ; Type (1 byte)
 +  : The type of message; e.g. read pattern, write pattern, etc.  ​
 +  ; Size (2 bytes)
 +  : the size of the _body_ of the message. ​ Can be 0 if the message has no arguments and no data.
 +
 +== Body ==    ​
 +  ; Body (N bytes)
 +  : The body of the message contains command arguments or  command data (e.g. a 303 pattern), both, or sometimes neither. The number of bytes contained in the body varies from message type to message type, and the correct size is always stored in the Size field in the header.
 +
 +== CRC ==
 +  ; CRC (1 byte)
 +  : The 8-bit CRC of the entire message (Header + Body). ​ The CRC  ensures that the message was correctly framed by the reciever (i.e. that the first byte at the receiver was the Type field of the header and not some random byte in the middle of the message) and that the there were no bit errors during transmission.  ​
 +
 +The format for the listing below is something like this:
 +
 +---- 
 +
 +== MESAGE_TYPE : ARG1 ARG2 ARG3 ==
 +  * ARG1 (x bytes)
 +  * ARG2 (y bytes)
 +  * ARG3 (z bytes)
 +  * x0xb0x responds with : response message type
 +
 +
 +==== c0ntr0l MESSAGE TYPES ====
 +
 +
 +The following messages are generated by the c0ntr0l application and sent 
 +to the x0xb0x over the serial port.  Many of these messages will cause the
 +x0xb0x to immediately respond with a message of its own.  These response ​
 +messages are described in the section below entitled "​x0xb0x MESSAGE TYPES"​.
 +The c0ntr0l application will wait for the response until the serial port 
 +times out, at which point it will print an error to the user to notify them
 +that the command failed.  ​
 +
 +
 +=== Pattern IO ===
 +The following messages read and write individual patterns ​
 +to/from the x0xb0x EEPROM.  ​
 +
 +== Write Pattern :   BANK LOC PATTERN ==
 +    * BANK + LOC (1 byte - one in each nibble)
 +    * PATTERN ​   (16 bytes)
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Read Pattern :   BANK LOC ==
 +    * BANK + LOC (1 byte - one in each nibble)
 +    * x0xb0x responds with: PATTERN message
 +
 +----
 +=== Pattern Manipulation ===
 +
 +Tell the x0xb0x to load a pattern from EEPROM into main memory
 +so that it plays when the R/S key is typed on either ​
 +the computer or on the synth. ​ Another way to look at this is that
 +you are setting the BANK and LOC using the knobs and switches on the
 +x0xb0x, which you can do individually using the other messages in this 
 +section. ​
 +
 +== Load Pattern :   BANK LOC ==
 +    * BANK + LOC (1 byte - one in each nibble)
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Set Bank :   BANK ==
 +    * BANK (1 byte)
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Get Bank: ==
 +    * x0xb0x responds with: BANK message
 +
 +== Set Pattern :   LOC ==
 +        * LOC (1 byte)
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Get Pattern: ==
 +    * x0xb0x responds with: LOC message
 +
 +----
 +=== Sequencer Status ===
 +
 +These messages are equivalent to setting and polling the state of the R/S 
 +button on the x0xb0x. ​ Basically, they tell the x0xb0x sequencer to start 
 +or stop.
 +
 +== Start Sequencer :   ==
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Stop Sequencer :   ==
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Get Sequencer State: ==
 +    *x0xb0x responds with : STATE message
 +
 +----
 +=== Set the current sync mode. ===
 +
 +== Set Sync :  SRC ==
 +    * SRC (1 byte) 
 +         ​* ​ 00 - no sync
 +         ​* ​ 01 - MIDI sync in
 +         ​* ​ 02 - MIDI sync out
 +         ​* ​ 03 - DINSYNC in
 +         ​* ​ 04 - DINSYNC out
 +    * x0xb0x responds with : SUCCESS message
 +
 +== Get Sync :   ==
 +    * x0xb0x responds with : SRC message
 +
 +----
 +=== Control the tempo ===
 +
 +== Set Tempo :  TEMPO ==
 +    * TEMPO (1 byte)
 +    * x0xb0x responds with : status message
 +
 +== Get Tempo :   ==
 +    * returns TEMPO message
 +
 +
 +==== x0xb0x MESSAGE TYPES ====
 +
 +The x0xb0x can return one of the following packets in response ​
 +to the c0ntr0l messages described above.  ​
 +
 +----
 +== SUCCESS message ​ :  SUCCESS ==
 +    * SUCCESS (1 byte boolean)
 +      * 0 - false
 +      * 1 - true
 +
 +== ERROR message ​ :  ERROR ==
 +        * ERROR (1 byte)\\
 +
 +----
 +=== Error Codes ===
 +
 +An error code to help debug why things went wrong
 +
 +== PATTERN message ​ :  PAT ==
 +    * PAT (16 bytes)
 +
 +== BANK message ​ :  BANK ==
 +    * BANK (1 byte)
 +
 +== LOC message ​ :  LOC ==
 +    * LOC (1 byte)
 +
 +== TEMPO message ​ :  TEMPO ==
 +    * TEMPO (1 byte)
 +
 +== SRC message ​ :  SRC ==
 +    * SRC (1 byte) 
 +         ​* ​ 00 - no sync
 +         ​* ​ 01 - MIDI sync in
 +         ​* ​ 02 - MIDI sync out
 +         ​* ​ 03 - DINSYNC in
 +         ​* ​ 04 - DINSYNC out
 +
 +== STATE message ​ :  STATE ==
 +    * STATE (1 byte)\\
 +      The current state of the R/S button. ​ i.e. whether the sequencer is playing or not.
 +
 +===== Future Features / TODO =====
 +
 +Future features (i.e. implement these in a future release...maybe....) :
 +  * Get/Set Accent
 +  * Get/Set Rest
 +  * Get/Set Slide
 +  * Get/Set Transpose
 +  * Low-level remote control
 +    * note_on
 +    * note_off
 +    * next note in pattern (when paused)
  
/home/ladyada/public_html/wiki/data/pages/x0x/serialprotocol.txt · Last modified: 2016/01/28 18:05 (external edit)