AYAB Serial Communication Specification, API v6

This document specifies the serial communication protocol used by the AYAB desktop software (host) to communicate with the firmware on the AYAB shield (device), starting with version 1.0.0 of both software and firmware.

Generic configuration

Asynchronous serial communication at 115200 baud, 8N1 without hardware flow control, encoded by SLIP protocol. SLIP packets are parsed sequentially. Checksums are calculated using the CRC8 algorithm as implemented in Dallas/Maxim application note 27.

Messages are limited in size to 64 bytes, not including the SLIP packet markers (0xC0 bytes), but taking into account the fact that under SLIP, data bytes equal to 0xC0 or 0xDB are escaped into two bytes, the maximum safe payload size is 32 bytes. This value is defined in the MAX_MSG_BUFFER_LEN constant in AYAB firmware und should be adapted accordingly in case of API message length changes.

Protocol for API v6

API version check

The host sends a reqInfo message to the device, which responds with cnfInfo indicating the API version used by its firmware.

Specification of knitting machine type

The host sends a reqInit message to the device specifying the knitting machine type in use. The device responds with cnfInit indicating the success or otherwise of the initialization.

Work request

The host waits for a indState message before requesting work. On startup, the device continuously checks for the initialization of the machine (carriage passed left hall sensor). When this happens, it sends an indState to tell the host that the machine is ready. After receiving this message, the host can send either a reqStart message to begin knitting, or a reqTest message to begin testing the hardware. The device confirms receipt of reqStart and reqTest messages by returning a cnfStart or cnfTest message, respectively.

Knitting operation

After a successful reqStart, and when it is ready to receive a further signal, the device begins to poll the host for line data with reqLine. (The device becomes ready after the carriage moves past the Hall sensor marking the beginning of the row.) The host answers with a cnfLine message containing information for the next row of knitting. After the row has been completed, the device sends another reqLine message to request the next line of data. When the host does not have any more lines to send, it sets the lastLine flag in its final cnfLine message.

Hardware test operation

After a successful reqTest, the device begins to poll the host for commands. The host polls the device for test results in a similar fashion. The device sends test results asynchronously, as zero-terminated text strings with an initial testRes id. The hardware test is terminated when the host sends quitCmd.

Message identifier format

Messages start with a byte that identifies their type. This byte is called "id" or "message id" in the following document. This table lists all the bits of this byte and assigns their purpose:

Bit Value Name Description and Values
7 128 message source 0 = the message is from the host
1 = the message is from the controller
6 64 message type 0 = the message is unprompted
1 = the message is confirmation of a request
5 32 test flag 0 = normal operation
1 = hardware test mode
4 16 debug flag 0 = not a debug message
1 = debug message
3 8 message identifier These are the values that identify the message.
2 4 message identifier
1 2 message identifier
0 1 message identifier

Message definitions (API v6)

The length is the total length with id and parameters. Note that the initial and terminal 0xc0 bytes are required by the SLIP protocol are not included in the message length.

Source Name ID Length Parameters
host reqStart 0x01 5 0xaa 0xbb 0xcc 0xdd
0xaa = start needle (Range: 0-198)
0xbb = stop needle (Range: 0-199)
0xcc = flags (bit 0: continuous reporting)
(bit 1: hardware beep on/off)
0xdd = CRC8 checksum
device cnfStart 0xC1 2 0xaa
0xaa = success (0 = success, other values = error)
device reqLine 0x82 2 0xaa
0xaa = line number (Range: 0 - 255)
host cnfLine 0x42 25/30 0xaa 0xbb 0xcc 0xdd[] 0xee
0xaa = line number (Range: 0 - 255)
0xbb = flags (bit 0: lastLine)
0xcc = color information
0xdd[] = binary pixel data (15 or 25 bytes)
0xee = CRC8 checksum
host reqInfo 0x03 1 Request firmware API version
device cnfInfo 0xC3 22 0xaa 0xbb 0xcc 0xdd 0xee[17]
0xaa = API Version Identifier
0xbb = Firmware Major Version
0xcc = Firmware Minor Version
0xdd = Firmware Patch Version
0xee[17] = Firmware Suffix (max. 16 chars + \0)
device indState 0x84 10 0xaa 0xbb 0xCC 0xcc 0xDD 0xdd 0xee 0xff 0xgg
0xaa = ready (0 = ready, other values = not ready)
0xbb = Finite State Machine state
0xCCcc = int left hall sensor value
0xDDdd = int right hall sensor value
0xee = carriage type:
FF = no carriage detected
0 = Knit carriage
1 = Lace carriage
2 = Garter carriage
0xff = carriage position (needle number)
0xgg = carriage direction:
0 = Left
1 = Right
other = direction not known
host reqTest 0x04 1 Request hardware test operation
device cnfTest 0xC4 2 0xaa
0xaa = success (0 = success, other values = error)
host reqInit 0x05 3 0xaa 0xbb
0xaa = machine type:
0 = KH-910 or KH-950
1 = KH-930, KH-940, or KH-965
2 = KH-270
0xbb = CRC8 checksum
device cnfInit 0xC5 2 0xaa
0xaa = success (0 = success, other values = error)
host reqQuit 0x0C 1 Request end of knitting operation
device cnfQuit 0xCC 2 0xaa
0xaa = success (0 = success, other values = error)
host helpCmd 0x26 1 Hardware test command requesting help on available commands.
host sendCmd 0x27 1 Hardware test command requesting that the device send a
test packet consisting of three bytes, 0x31 0x32 0x33.
host beepCmd 0x28 1 Hardware test command requesting that the device beep.
host readCmd 0x29 1 Hardware test command requesting that the device read the
EOL (end of line) Hall sensors and the position encoders.
host autoCmd 0x2A 1 Hardware test command requesting that the device read the
EOL sensors and position encoders once per second, sending
a testRes message reporting the information each time.
host testCmd 0x2B 1 Hardware test command requesting that the device test the
solenoids by activating odd and even sensors alternately,
once per second.
host quitCmd 0x2C 1 Hardware test command requesting that the device quit
hardware test mode and return to normal operation.
host setCmd 0x2D 3 0xaa 0xbb
0xaa = index of solenoid to set
0xbb = solenoid value (0 = unset, 1 = set)
device testRes 0xEE var A string containing hardware test information.
The length is variable. The string terminates with 0.
device debug 0x9F var A debug string, of variable length, terminating in 0.

Error codes

As of APIv6, the only important distinction is between Success (0x00) and any other value. Informative error codes are provided for diagnostic purposes (that is, for debugging). Non-zero error codes are subject to change: such changes will be considered non-breaking.

Value Meaning
0x00 Success
Message not understood:
0x01 Expected longer message
0x02 Unrecognized MsgId
0x03 Unexpected MsgId
0x04 Checksum error
Invalid arguments:
0x10 Machine type invalid
0x11 Needle value invalid
0x12 Null pointer argument
0x13 Argument(s) invalid or incompatible
Device not initialized:
0x20 Machine type not initialized
0x21 Carriage not initialized
0x22 Direction not initialized
0x23 Beltshift not initialized
Machine in wrong FSM state:
0xE0 MACHINE_STATE_INIT
0xE1 MACHINE_STATE_READY
0xE2 MACHINE_STATE_KNIT
0xE3 MACHINE_STATE_TEST
0xEF WRONG_MACHINE_STATE
Generic error codes:
0xF0 Warning (ignorable error)
0xF1 Recoverable error
0xF2 Critical error
0xF3 Fatal error
0xFF Unspecified failure