System Exclusive Protocol

K2vx System Exclusive Implementation

Chapter 30
System Exclusive Protocol
K2vx System Exclusive Implementation
The MIDI System Exclusive capabilities of the K2vx allow you to manipulate objects in the
K2vxÕs memory from a computer system, another K2vx, or a MIDI data recorder. The following
is a reference to the SysEx protocol used by the K2vx. This information can be used to build a
simple object librarian software program. A word of adviceÑbefore you begin experimenting
with SysEx, make sure you have saved anything of value in RAM to disk.

NOTE: To support new features and changes in the K2vx line of products, the internal program
structure has been changed from that of the K2vx. Due to these changes, you cannot transfer a K2vx
program to a K2vx, or a K2vx program to a K2vx via MIDI system exclusive. The K2vx software will
continue to be enhanced, and in the future the K2vx will be capable of accepting K2vx programs over
MIDI. As a result of this, computer based K2vx editor/librarians will not currently work with the K2vx,
unless they have been revised to accommodate the changes.

Common Format
In the following discussion, the Þelds of the K2vx System Exclusive Protocol messages are
notated asÉ

field(length)
Éwhere ÔÞeldÕ is the name of the particular information Þeld in the message, and ÔlengthÕ is
either 1, 2, 3, or n, representing the number of sequential MIDI bytes that make up the Þeld. A
length of ÔnÕ means that the Þeld is of a variable length that is determined by its contents or sub-
Þelds.

All K2vx SysEx messages have the common format:

sox(1) kid(1) dev-id(1) pid(1) msg-type(1) message(n) eox(1)

ÔsoxÕ is always F0h, and represents start of System Exclusive.

ÔkidÕ must be 07h, and is the Kurzweil Manufacturer ID.

Ôdev-idÕ is Device ID. The K2vx will recognize a SysEx message if the Ôdev-idÕ is the same is the
SysX ID parameter from the MIDI Receive page (from the top level, press the MIDI mode
button and the RECV soft button.) If the K2vxÕs SysX ID parameter is set to 127, it will
recognize SysEx messages no matter what the Ôdev-idÕ is.

ÔpidÕ is the Product IdentiÞer, and must be 78h (120 decimal), indicating the SysEx message is
for the K2vx.

Ômsg-typeÕ is the identiÞer of one of the K2vx SysEx messages deÞned below, and ÔmessageÕ is
the variable-length message contents.

ÔeoxÕ is always F7h, for end of System Exclusive.

Data Formats
K2vx SysEx messages are subdivided into Þelds that contain data in different formats. The
various Þelds are shown in the Messages section below. Within a message, any Þelds for values
that can be bigger than 7 bits are broken into 7 bit chunks. Thus two MIDI bytes gives 14 bits,
three bytes gives 21 bits. The signiÞcant bits are right justiÞed in the Þeld. All bytes in a Þeld
must be present no matter what the value is. For example, an object type of 132 would be split
into two MIDI bytes in a ÔtypeÕ Þeld as 01 04:

30-1
System Exclusive Protocol
K2vx System Exclusive Implementation

decimal: 132

binary: 10000100

binary encoding for type(2) field: 0000001 0000100

decimal encoding for type(2) field: 1 4

Object name Þelds are sent as a string of ASCII values in a ÔnameÕ Þeld, with one MIDI byte of
zero as a string terminator. For example, the name ÒGlass KazooÓ would be sent as letters:

G l a s s _ K a z o o <null>

hex encoding for ‘name’ field: 47 6C 61 73 73 20 4B 61 7A 6F 6F 00

Data sizes and offsets are sent in the ÔsizeÕ and ÔoffsÕ Þelds.These values refer to quantities of 8-
bit bytes in the K2vxÕs memory, which is packed in the ÔdataÕ Þeld.

Binary data in the ÔdataÕ Þeld is sent by in one of two formats, according to the value of the
ÔformÕ Þeld. If the ÔformÕ Þeld equals zero, the data is transmitted as 4 bits or one ÒnibbleÓ in
every MIDI byte. If the ÔformÕ Þeld equals one, then the data is sent as a compressed bit-stream,
with 7 bits per midi byte. The bit-stream format is more efÞcient for data-transmission, while
the nibble format is easier to read (and write software for).

For example, to send the following four K2vx data bytes,

hex: 4F D8 01 29
decimal: 79 216 1 41
binary: 01001111 11011000 00000001 00101001

eight MIDI bytes are sent in ÒnibbleÓ format:

hex: 04 0F 0D 08 00 01 02 09
decimal: 4 15 13 8 0 1 2 9
binary: 0000100 0001111 0001101 0001000 0000000 0000001 0000010 0001001

Þve MIDI bytes are sent in bit-stream format:

hex: 27 76 0 12 48
decimal: 39 118 0 18 72
binary: 0100111 1110110 0000000 0010010 1001000

The bit-stream format can be thought of as taking the binary bits of the K2vx data and, starting
from the left, slicing off groups of 7 bits. Note that the trailing bits are set to zero.

After the ÔdataÕ Þeld, there is another Þeld, ÔxsumÕ. This is a checksum Þeld which is calculated
as the least signiÞcant 7-bits of the sum of all of the MIDI bytes that make up the ÔdataÕ Þeld.

Messages
This section deÞnes the K2vx System Exclusive message formats. Each message has a message
type (that goes in the Ômsg-typeÕ Þeld; see Common Format, above), followed by the Þeld
deÞnitions of the message.

30-2
 System Exclusive Protocol
K2vx System Exclusive Implementation

DUMP = 00h type(2) idno(2) offs(3) size(3) form(1)

Érequests the K2vx to send a data dump of an object or portion thereof. ÔtypeÕ and ÔidnoÕ
identify the object. ÔoffsÕ is the offset from the beginning of the objectÕs data and ÔsizeÕ describes
how many bytes should be dumped starting from the offset. ÔformÕ indicates how the binary
data is to transmitted (0=nibblized, 1=bit stream). The response is a LOAD message:

LOAD = 01h type(2) idno(2) offs(3) size(3) form(1) data(n) xsum(1)

Éwhich writes data into the speciÞed object, which must exist. Both load and dump operate on
the object data only. The response to a load message will be

DACK = 02h type(2) idno(2) offs(3) size(3)

Émeaning Òload acceptedÓ, or

DNAK = 03h type(2) idno(2) offs(3) size(3) code(1)

Émeaning Òload not accepted.Ó The ÔcodeÕ Þeld indicates the cause of the failure, as follows::

code meaning

1 Object is currently being edited

2 Incorrect checksum
3 ID out of range (invalid)
4 Object not found (no object with that ID exists)
5 RAM is full

To request information about an object, use:

DIR = 04h type(2) idno(2)

The ÔtypeÕ and ÔidnoÕ identify the object. The response is an INFO message:

INFO = 05h type(2) idno(2) size(3) ramf(1) name(n)

This is the response to DIR, NEW, or DEL. If object is not found, ÔsizeÕ will be zero and ÔnameÕ
will be null. ÔramfÕ is 1 if the object is in RAM.

NEW = 06h type(2) idno(2) size(3) mode(1) name(n)

Écreates a new object and responds with an INFO message of the created object. The objectÕs
data will not be initialized to any default values. If ÔidnoÕ is zero, the Þrst available object ID
number will be assigned. If ÔmodeÕ is 0, the request will fail if the object exists. If ÔmodeÕ is 1,
and the object exists in ROM, a RAM copy will be made. If ÔmodeÕ is 1, and the object exists in
RAM, no action is taken.

DEL = 07h type(2) idno(2)

Édeletes an existing object and responds with an INFO message for the deleted object. If there
is only a RAM copy of the object, the response will indicate that the object doesnÕt exist
anymore. However, if the deletion of a RAM object uncovers a ROM object, the INFO response
will refer to the ROM object. A ROM object cannot be deleted.

30-3
System Exclusive Protocol
K2vx System Exclusive Implementation

CHANGE = 08h type(2) idno(2) newid(2) name(n)

Échanges the name and/or ID number of an existing object. If ÔnewidÕ is zero or ÔnewidÕ equals
ÔidnoÕ, the ID number is not changed. If ÔnewidÕ is a legal object id number for the objectÕs type
, then the existing object will be relocated in the database at the new ID number. This will cause
the deletion of any object which was previously assigned to the ÔnewidÕ. If the ÔnameÕ Þeld is
null, the name will not change. Otherwise, the name is changed to the (null-terminated) string
in the ÔnameÕ Þeld.

WRITE = 09h type(2) idno(2) size(3) mode(1) name(n) form(1) data(n) xsum(1)

Éwrites an entire objectÕs data directly into the database. It functions like the message
sequence DEL followed by NEW followed by a LOAD of one complete object data structure. It
Þrst deletes any object already existing at the same type/ID. If no RAM object currently exists
there, a new one will be allocated and the data will be written into it. The object name will be
set if the ÔnameÕ string is non-null. The response to this message will either be a DACK or a
DNAK, as with the load message. The ÔoffsÕ Þeld of the response will be zero. The K2vx will
send a WRITE message whenever an object is dumped from the front-panel (using a ÒDumpÓ
soft-button), or in response to a READ message.

The ÔmodeÕ Þeld is used to determine how the ÔidnoÕ Þeld is interpreted.

If ÔmodeÕ = 0:

The ÔidnoÕ speciÞes the absolute ID number to write to, which must exist.(must be valid)

If ÔidnoÕ equals zero, write to the Þrst available ID number.

If ÔmodeÕ = 1

The object is written at the Þrst available ID number after what is speciÞed by ÔidnoÕ.

It doesnÕt matter if ÔidnoÕ is a legal ID number. Remember that for certain object types, the 100s
through 900s banks allow fewer than 100 objects to be stored (for example, the 100s bank will
store preset effects at IDs 100Ñ109 only). In this mode, if ÔidnoÕ was 313, the object would be
written to ID 400 if available.

READ = 0Ah type(2) idno(2) form(1)

Érequests the K2vx to send a WRITE message for the given object. No response will be sent if
the object does not exist.

READBANK = 0Bh type(2) bank(1) form(1) ramonly(1)

Érequests the K2vx to send a WRITE message for multiple objects within one or all banks.

ÔtypeÕ and ÔbankÕ specify the group of objects to be returned in WRITE messages. The ÔtypeÕ
Þeld speciÞes a single object type, unless it is zero, in which case objects of all user types will be
returned (see object type table below). The ÔbankÕ Þeld speciÞes a single bank, 0-9, unless it is
set to 127, in which case objects from all banks will be returned.

ÔformÕ requests the format of the binary data in the WRITE messages. If ÔramonlyÕ is one, only
objects in RAM will be returned. If ÔramonlyÕ is zero, both RAM and ROM objects are returned.

30-4
 System Exclusive Protocol
K2vx System Exclusive Implementation

The responses, a stream of complete WRITE messages, will come out in order of object type,
while objects of a given type are in order by ID number, from lowest to highest. If no objects are
found that match the speciÞcations, no WRITE messages will be returned. After the last WRITE
message, an ENDOFBANK message (deÞned below) is sent to indicate the completion of the
bank dump.

The K2vx will insert a small delay (50ms) between WRITE messages that it issues in response to
a READBANK message.

A bank dump can be sent in its entirety to another K2vx, which will add all of the objects
contained in the dump to its own object database. IMPORTANT: If the K2vx receives a large
bank dump for a bank or banks that already contain objects, errors may result unless the sender
waits for the DACK message before sending the next objectÕs WRITE message. One way to
avoid transmission errors such as this is to make sure that the bank being dumped is clear in
the K2vx before sending the dump, so that the K2vx will not miss parts of the dump while its
CPU is busy deleting already existing objects. This can be done using the DELBANK message
(deÞned below). If the destination bank in the K2vx is pre-cleared, it is not necessary to wait for
the DACK before sending. Even if the sender chooses not to wait for the DACK before sending
the next message, it may be necessary to preserve the 50ms delay between the WRITE
messages.

Due to the large amount of incoming data during a bank dump containing many objects, the
receiving K2vx may have a more sluggish response to front-panel use and keyboard playing
during the data transfer. This is normal behavior and the machine will become fully responsive
as soon as the dump is Þnished.

DIRBANK = 0Ch type(2) bank(1) ramonly(1)

This is similar to the READBANK message. The DIRBANK message requests an INFO message
(containing object size, name, and memory information) be returned for each object meeting
the speciÞcations in the ÔtypeÕ and ÔbankÕ Þelds. Following the last INFO response will be an
ENDOFBANK message.

ENDOFBANK = 0Dhtype(2) bank(1)

This message is returned after the last WRITE or INFO response to a READBANK or
DIRBANK message. If no objects matched the speciÞcations in one of these messages,
ENDOFBANK will be the only response.

DELBANK = 0Eh type(2) bank(1)

This message will cause banks of objects (of one or all types) to be deleted from RAM. The
ÔtypeÕ and ÔbankÕ speciÞcations are the same as for the READBANK message. The deletion will
take place with no conÞrmation. SpeciÞcally, the sender of this message could just as easily
delete every RAM object from the K2vx (e.g. ÔtypeÕ = 0 and ÔbankÕ = 127) as it could delete all
effects from bank 7 (e.g. ÔtypeÕ = 113, ÔbankÕ = 7.)

MOVEBANK = 0Fh type(2) bank(1) newbank(1)

This message is used to move entire banks of RAM objects from one bank to another. A speciÞc
object type may be selected with the ÒtypeÓ Þeld. Otherwise, if the ÒtypeÓ Þeld is unspeciÞed
(0), all object types in the bank will be moved. The ÒbankÓ and ÒnewbankÓ Þelds must be
between 0 and 9. The acknowledgement is an ENDOFBANK message, with the ÒbankÓ Þeld

30-5
System Exclusive Protocol
K2vx System Exclusive Implementation

equal to the new bank number. If the operation canÕt be completed because of a bad type or
bank number, the ENDOFBANK message will specify the old bank number.

PANEL = 14h buttons(3n)

Ésends a sequence of front-panel button presses that are interpreted by the K2vx as if the
buttons were pressed at its front-panel. The button codes are listed in a table at the end of this
chapter. The K2vx will send these messages if the Buttons parameter on the XMIT page in MIDI
mode is set to On. Each button press is 3 bytes in the message. The PANEL message can include
as many 3-byte segments as necessary.

Byte 1 Button event type:

08h Button up

09h Button down

0Ah Button repeat

0Dh Alpha Wheel

Byte 2 Button number (see table)

Byte 3 Repeat count (number of clicks) for Alpha Wheel; the count is the delta (difference)
from 64—that is, the value of the byte minus 64 equals the number of clicks. A Byte
3 value of 46h (70 dec) equates to 6 clicks to the right. A Byte 3 value of 3Ah (58
dec) equates to six clicks to the left. For example, the equivalent of 6 clicks to the
right would be the following message:

(header) 14h 0Dh 40h 46 (eox)

For efÞciency, multiple button presses should be handled by sending multiple Button down
bytes followed by a single Button up byte (for incrementing with the Ô+Õ button, for instance. )

Object Types
These are the object types and the values that represent them in ÔtypeÕ Þelds:

Type ID (decimal) ID (hex) ID(hex, ‘type’ field)

Program 132 84h 01h 04h

Keymap 133 85h 01h 05h
Effect 113 71h 00h 71h
Song 112 70h 00h 70h
Setup 135 87h 01h 07h
Soundblock 134 86h 01h 06h
Velocity Map 104 68h 00h 68h
Pressure Map 105 69h 00h 69h
Quick Access Bank 111 6Fh 00h 6Fh
Intonation Table 103 67h 00h 67h

30-6
 System Exclusive Protocol
K2vx System Exclusive Implementation

Master Parameters
The Master parameters can be accessed as type 100 (00h 64h), ID number 16. Master parameters
cannot be accessed with any of the Bank messages.

Button Press Equivalence Table

Button Code (hex) Button Code(hex)

Alphanumeric pad Soft-Buttons ‘A-F’

zero 00 A ‘(leftmost) 22
one 01 B 23
two 02 C 24
three 03 D 25
four 04 E 26
five 05 F (rightmost) 27
six 06 AB 28
seven 07 CD (two center) 29
eight 08 EF 2A
nine 09 YES 26
+/- 0A NO 27

Alphanumeric pad Edit/Exit

CANCEL 0B EDIT 20
CLEAR 0C EXIT 21
ENTER 0D

Navigation Mode Selection

Plus (+) 16 PROGRAM 40

Minus (-) 17 SETUP 41
Plus and Minus 1E QUICK ACCESS 42
CHAN/BANK Inc 14 EFFECTS 47
CHAN/BANK Dec 15 MIDI 44
CHAN/BANK Inc/Dec 1C MASTER 43
Cursor Left 12 SONG 46
Cursor Right 13 DISK 45
Cursor Left/Right 1A
Cursor Up 10
Cursor Down 11
Cursor Up/Down 18

30-7
System Exclusive Protocol
K2vx System Exclusive Implementation

The next four commands allow you to read the screen display, both text and graphics layers.

ALLTEXT = 15h
Érequests all text in the K2vxÕs display.

PARAMVALUE = 16h
Érequests the current parameter value.

PARAMNAME = 17h
Érequests the current parameter name.

GETGRAPHICS = 18h
Érequests the current graphics layer.

SCREENREPLY = 19h
This is the reply to ALLTEXT, PARAMVAL, PARAMNAME, GETGRAPHICS, or
SCREENREPLY.

The reply to ALLTEXT will be 320 bytes of ASCII text (the display has 8 rows of 40 characters
each). If you receive less than that, then the screen was in the middle of redrawing and you
should request the display again.

The reply to PARAMVALUE will be a variable length ASCII text string. Some values (like
keymaps, programs, samples, etc.) include their ID number in the text string (e.g., "983 OB
Wave 1"). Some messages are also padded with extra spaces.

The reply to PARAMNAME will be a variable length ASCII text string. In cases where there is
no parameter name (like on the program page) there will just be the single 00 null terminator.

The reply to GETGRAPHICS will be 2560 bytes of information. The 6 least signiÞcant bits of
each byte indicate whether a pixel is on or off. If pixels are on over characters, the text becomes
inverted. Characters on the K2vx display are a monospaced font with a height of 8 pixels and a
width of 6 pixels.

30-8