Packet Interface - how it works

The packet interface is the standard interface to operate the module when connected to a microcontroller or any other programmable device such like a SPS. The interface is mostly binary coded.

Theory of Operation

The packet interface or "application programming interface" (API) allows to use the Avisaro 2.0 product series flexible and efficiently. It is designed to be used together with any programmable device such as a micro controller or industrial control ('SPS'). The packet interface uses binary commands and a simple frame format for communication. If not all features, such as multiple connections in parallel, are used, the text interface could be considered as an alternative. A mix of both is also allowed.

Using the packet interface, the communication scheme is 'ping-pong'. The user application sends a command to the Avisaro module which in return answers with a packet. There is no unsolicited data coming from the Avisaro module.

Frame Format

There are two packet types to communicate: "data / command packet" and "one byte commands". The later one is used for acknowledgements and flow control. The packet format is the same for sending and receiving data:

Header	Length		Payload			CRC
Byte	MSB	LSB	Command	Parameter	Data	MSB	LSB

 

The length value includes only the field “Payload”. Header Byte, length itself and CRC are not counted.

Payload is usually a command byte followed by some parameters. To send data, a command byte is used followed by the 'handle number' and the data to send.

CRC is calculated as described in attachment __ to this document. A CRC of 0x0000 is defined as ‘ignore CRC’ – thus a good way to reduce complexity and performance requirements.

The header byte (one byte in length) describes the type of information:

 

Header Byte	Packet type (frame or 'one byte')	Content	Description
0x81	Frame	Data / Commands	This frame contains data to be send or a command such as “connect to tcp address” or "send this data using connection no x". Valid acknowledges to this frame are 0x84 (ack) or 0x85 (nack).
0x82	Byte	Nothing	This is the Re-Sync byte. If communication is out of sync (e.g broken while a packet was in progress) 0x82 can be sent multiple times until the module responds with ACK or NACK.
0x84	Frame	Positive Ack (ACK)	The frame was received and the Avisaro module is ready to receive new data
0x85	Frame	Negative Ack (NACK)	The fame send to the Avisaro module was discarded due to some error condition
0x86	Byte	Nothing	This is the Continue-Byte. Some responses do not fit into a single packet. By sending 0x86 the host can request subsequent packets until the response is complete.
0xFF	Byte	Nothing	‘Null’ operation. Particular when SPI or I2C interface is used – this byte is used to fill data line when no other valid data is available.

 

Example "WLAN"

Once a connection is opened (i.e. using the connect command) data is transmitted using the 'send data' command:

 

0x81, 0x00, 0x08, 0x84, 0x00, 0x65, 0x68, 0x61, 0x6c, 0x6c, 0x6f, 0x00, 0x00

With
0x81 being the header byte;
0x00, 0x08 the length;
0x84 the send data command;
0x00, 0x65 the internal handle number (defined when using the connect command);
0x68, 0x61, 0x6c, 0x6c, 0x6f the data ("hallo"); and the
0x00, 0x00 the CRC (not used in this example).

If all is ok, the Avisaro module answers with:

0x84, 0x00, 0x00, 0x56, 0xBE

 

With

0x84 being the positive acknowledge;
0x00, 0x00 being the length (nothing to return), and
0x56, 0xBE being the CRC of this empty frame.

The Avisaro module could also answers with:

0x85, 0x00, 0x01, 0x1C, 0x83, 0x2D

 

With

0x85 being the answer "negative acknowledge;
0x00, 0x01 the length;
0x1C the error code (handle number not defined),
0x83, 0x2D the CRC.

 

In this example the handle number was not defined - the user tried to send data over a connection which was not established.