- Introduction
- Message Structure
- RS-232 Protocol 1.RS-232 Time Outs and Resends
- SPI Protocol
- USB Protocol
- Ethernet TCP/IP Protocol
- Error Handling
Introduction
This document will explain the message structure and protocol of Audio Weaver commands. It will explain the details of each transport method's protocol. For a complete list of Audio Weaver commands, see the file ProxyIDs.h
Message Structure
Audio Weaver Tuning commands and replies use 32-bit words, with a 1 word header and 1 word CRC wrapping the payload as shown in the image below.
The length of the message includes the header and CRC word. Thus, the shortest possible message – one without a payload – is two words in length.
The CRC word is a 32-bit value and computed so that when all words of the message, including the CRC, are XOR'ed together, the result is 0. The following code computes the CRC of a packet prior to transmission:
nLen = g_PacketBuffer[0] >> 16;
DWORD crc=0;
for(i=0; i < (nLen-1); i++)
{
crc^=g_PacketBuffer[i];
}
g_PacketBuffer[nLen-1] = crc;
This function is also defined in AWECoreUtils.h for use by the integrator.
On the target side, the CRC calculations are handled in awe_packetProcess(). It checks the CRC of the received message and computes the checksum of the reply.
RS-232 Protocol
Audio Weaver messages (commands and replies) are arrays of 32-bit integers. In the case of RS-232 communications, we add a lower level byte-by-byte protocol which adds another level of robustness to the communication link. This additional robustness is critical in RS-232 which is more susceptible to bit corruption and dropped bytes.
Each 32-bit word within the message array is expanded into 5 bytes using the code:
ch = (unsigned char)(0x80 | s_msg_word & 0x7F); ch = (unsigned char)(0x80 | (s_msg_word >> 7) & 0x7F); ch = (unsigned char)(0x80 | (s_msg_word >> 14) & 0x7F); ch = (unsigned char)(0x80 | (s_msg_word >> 21) & 0x7F); ch = (unsigned char)(0x80 | (s_msg_word >> 28) & 0x7F);
7 data bits are taken at a time from each message word and the high bit is set. (For the last character, only the low 4 data bits are used.)
The data is then encapsulated within a series of protocol bytes:
Start Byte 0x02 Sequence Byte 0x30 to 0x39 (ASCII “0” to “9”) Message Bytes 0x80 to 0xFF. 5 bytes at a time. Stop Byte 0x03
With this design, the protocol bytes are unique. That is, the protocol bytes (0x02, 0x03, 0x30-0x39) are never found within the data bytes since the data bytes always have the high bit set. This makes it easy to identify the start and end of data packets. The sequence byte starts at 0x30, increments 1 for each successful transmission, and then wraps from 0x39 to 0x30. The sequence byte is used to identify retransmissions.
For example, consider the command PFID_GetProfileValues with ID = 43. The message sent from the PC to the target processor is:
Which translates into the 32-bit words:
0x0002002b 0x0002002b (CRC is the same for 1 word payloads)
The 32-bit words are expanded into 5 bytes each:
0x0002002b -> 0xAB 0x80 0x88 0x80 0x80 0x0002002b -> 0xAB 0x80 0x88 0x80 0x80
Adding the remaining protocol bytes, the sequence sent is:
0x02 (start byte) 0x3X (sequence) 0xAB 0x80 0x88 0x80 0x80 (payload) 0xAB 0x80 0x88 0x80 0x80 (CRC) 0x03
RS-232 Time Outs and Resends
Audio Weaver has several configurable timeouts. After a message is sent to the target processor the Server waits for a reply. When using the RS232 protocol, if the start of the reply is not received within 50 msec the Server declares a time out and resends the message (SingleCharTimeout). If the entire reply is not received within 150 msec then a timeout is declared (TotalTimeoutTimeout).
When a timeout occurs, the Server resends the message. If the same message has been sent 3 times (2 timeouts), then the Server will declare an error and inform the user.
The timeout periods can be modified to match your application. For example, edit the AWE_Server.ini file and change the following lines to read:
[TimeOut] SingleCharTimeout=200 TotalTimeoutTimeout=1000 RS232RetryCount=3
(All times are in milliseconds)
SPI Protocol
The Audio Weaver SPI protocol mirrors the 32-bit packet structure. There are two differences:
- The 32-bit synchronization word 0xDEADBEEF is sent before each message.
- The 4 bytes within each 32-bit word as swapped. 0x12345678 it turned into 0x78563412.
For example, consider the command “PFID_GetProfileValues” with ID = 43 (0x2b). The message sent from the PC to the target processor is:
This translates into the 32-bit words:
0x0002002b 0x0002002b (CRC is the same for 1 word payloads)
The overall message sent is:
0xDEADBEEF -> 0xEFBEADDE 0x0002002B -> 0x2B000200 0x0002002B -> 0x2B000200
After a message is received by the target processor and the message is being processed, the SPI output buffer will be set to the “not ready” word 0xA3A3A3A3. This will allow a host processor to poll the SPI interface waiting for the target processor to complete message processing. The target processor will continue to transmit the not ready word until the message has been processed. At this point, it will switch over to the sync word followed by the complete message.
If the host processor continues to read beyond the end of a reply from the target, then the target will return 0xFFFFFFFF.
USB Protocol
Audio weaver USB communication is based on the USB HID protocol. Audio Weaver commands and replies are encapsulated in one or more 56-byte HID report packets operating over a 64-byte USB pipe. Each HID report packet starts with the HID report ID. Audio Weaver uses HID Report ID 1. If USB HID communications are used for other firmware features, those features must use a HID Report ID other than 1.
Following the HID report ID is a one byte seq number and a two byte length field.
Ethernet TCP/IP Protocol
Audio Weaver ethernet communication is as simple as passing commands/replies via a TCP/IP socket.
Error Handling
Several different types of errors can occur within the communication link. See Errors.h for a complete list of errors.
Receive Errors
If the received message has been formatted (such as wrong protocol bytes or the payload is not a multiple of 5 bytes in the case of RS-232) then the target processor silently ignores the message. The PC/Host will time out and then retransmit the message with the same sequence number.
If the received message has a CRC error, then the target processor will reply with message type PFID_Undefined. The message payload will be set to E_BADPACKET. When the PC/Host processor receives this reply, it will increment the sequence number and then resend the previous message.
Reply Errors
Assume that the message was properly received by the target processor and executed by the message handler in PacketAPI.c. The reply message is formed and then sent back to the host processor. The sequence number in the reply equals the sequence number of the original message from the PC/Host.
Now, assume that an error occurs in the transmission of the reply back to the PC/Host processor. When the PC/Host detects the error, it should resend the original message with the same sequence number. When the message is received by the target processor, the target processor sees that the sequence number is unchanged from the last message; this flags an error in the previous reply. The target processor does not re-execute the last command. Instead, it simply sends the reply again.
Once a message is received through the tuning interface, it will be processed by awe_packetProcess(). The first step is to check the CRC. If there is a CRC error, the target processor returns a 3 word message to the host (PC). The message type is:
PFID_Undefined
and the message payload is
E_BADPACKET
When this error is received by the host (PC) the last message should be retransmitted.
The Audio Weaver Server application does extensive error handling on the received data. If an error occurs, the Server retransmits the packet 3 times before hard failing.
