AKO Protocol Specification

Version 1.0 (22 December 1999)

Contents

  1. Introduction
  2. Message transport
    1. Message framing
  3. Message Format
  4. Messages
    1. CIF messages
    2. Digital I/O messages
    3. Analog input messages
    4. Analog output messages
    5. Stepper motor messages
  5. Message details
    1. CIF messages
    2. Digital I/O messages
    3. Analog input messages
    4. Analog output messages
    5. Stepper motor messages
  6. Component classes
  7. Component types
    1. Digital I/O components
    2. Analog input components
    3. Analog output components
    4. Stepper motor components
  8. Protocol procedures
    1. Checksum calculation
    2. Ping
    3. Joining the network
    4. Sending unsolicited messages
    5. Immediate success protocol extension

Introduction

The AKO protocol is the standard protocol for components and the main controller system to communicate with each other in the Project AKO RDK.  The AKO protocol uses the I2C protocol developed by Philips for the addressing and transport layers.  The AKO protocol extends I2C by providing a standardized message format and error checking.  Additionally, it defines specific message formats for most communications between components.

This document will describe the use of I2C to transport messages, the canonical message format, predefined message formats, and procedures AKO compliant components should follow.  Basic knowledge of the I2C protocol and terminology is assumed throughout this specification.

Top

Message transport

AKO protocol messages are transported via the I2C protocol.  7-bit I2C addressing is used, in either standard or fast mode (if any standard mode devices are connected, all devices will be forced to use standard mode, as per the I2C specification).  All messages are transported in master transmitter/slave receiver mode. 

Message framing

When a master sends a message to another component, it will frame the message by creating a START condition on the bus, as per the I2C specification.  The slave's I2C address is then transmitted, also as per the I2C specification.  Once the slave receiver has been addresses, transmission of an AKO packet begins.  The end of the packet is indicated by a STOP or repeated START condition on the I2C bus.  The entire AKO packet must be sent in between the START condition and STOP or repeated START condition.  Packets may not be broken up and spanned across multiple I2C frames.

Message framing
  1. Send I2C START condition
  2. Send 7-bit slave address
  3. Send entire AKO message packet
  4. Send I2C STOP or repeated START condition

Top

Message format

All AKO protocol messages follow a standard format to facilitate the decoding and management of messages by the comonents and device manager.

AKO message format
Field Description Offset Length
LENGTH Total length of packet in bytes (including LENGTH byte) 0 1
SENDER_I2C The I2C address of the device sending this message 1 1
INVARIANT When a message is being sent in response to a request packet, the INVARIANT in the response packet will match the INVARIANT in the original request packet.  This field can be used to track packets. 2 1
MESSAGE This field identifies the message type of this packet. 3 1
DATA The message DATA follows the MESSAGE field.  The length and contents of the DATA field depend on the MESSAGE type of this packet, and in some cases the type of device sending the packet. 4 n
CHECKSUM This field is a modulo-255 sum of all preceding bytes in the packet.  The CHECKSUM byte is not including in checksum calculation. 4 + n 1

Top

Messages

The AKO protocol defines messages that all components should understand and respond to.  These messages are known as CIF message, because they are handled by the component independent firmware (CIF) of the components.  In addition to CIF messages, many messages are applicable to specific component types.  These messages are known as CSF messages, because they are handled by the component specific firmware (CSF) of the components.  MESSAGE fields less than 0x10 are reserved for CIF messages.  These messages are intercepted by the CIF and will not be passed onto the CSF.

The following CIF messages are currently defined:

CIF messages
MESSAGE Name Description Implemented
0x00 IDENT_REQ Requests a component to send an IDENT_RESP packet back. N/A
0x01 IDENT_RESP Sent in response to an IDENT_REQ packet.  This message identifies the class and type of component sending the message. N/A
0x02 CAPS_REQ Requests a component to send a CAPS_REQ packet back. N/A
0x03 CAPS_RESP Sent in response to a CAPS_REQ packet.  This message identifies the capabilities and limits of the device.  The format of the CAPS_RESP message is dependent upon the device class and type sending the message. N/A
0x04 INIT_MSG Sent from a component to the device manager to inform the device manager that the component is just joined the network. N/A
0x05 CONFLICT_MSG Sent from a component to the device manager to inform the device manager that if can not join the network because it's I2C address conflicts with a component already on the network. N/A
0x06 CHGI2C_MSG Sent to a component to reprogram it's I2C address. N/A

The following CSF messages are currently defined.

Digital I/O messages
MESSAGE Name Description Implemented
0x10 DIO_INTR Configures the interrupt utility of a component.  Sent by main controller to component. N/A
0x11 DIO_TRIS Sets the direction of the bits on a port or ports.  Sent by main controller to component. N/A
0x12 DIO_OUT Outputs data to a port or ports.  Sent by main controller to component. N/A
0x13 DIO_INREQ Request that the component send back the input signals from a port or ports.  Sent by main controller to get a DIO_IN message back. N/A
0x14 DIO_IN Sends the input signals of a port or ports.  Sent by component to main controller. N/A

Analog input messages
MESSAGE Name Description Implemented
0x20 AI_INTR Configures the interrupt utility of the component.  Sent by main controller to componenet. N/A
0x23 AI_INREQ Request that the component send back the input signals from a port or ports. Sent by main controller to get an AI_IN message back. N/A
0x24 AI_IN Sends the input signals of a port or ports. Sent by component to main controller. N/A
0x25 AI_VREF Sets the Vref for the A/D converter on components which support this feature. N/A

Analog output messages
MESSAGE Name Description Implemented
0x32 AO_OUT Outputs data to a port or ports. Sent by main controller to component. N/A
0x35 AO_VREF Configures the Vref for the D/A converter on components that support this feature. N/A

Stepper motor messages
MESSAGE Name Description Implemented
0x40 SM_ROTATE Tells a stepper motor to turn a specified number of steps in a certain direction.  Sent by the main controller to a component. N/A

Top

Message details

This section describes in detail the message format of the messages described in the last section.

CIF messages

IDENT_REQ
No other information is transmitted in an IDENT_REQ message.

IDENT_RESP message
Field Description Offset Length
DEV_CLASS Identifies the device class to which this component belongs. 0 1
DEV_TYPE Identifies the specific device type within the device class. 1 1

CAPS_REQ
No other information is transmitted in a CAPS_REQ message.

CAPS_RESP message
Field Description Offset Length

INIT_MSG message
Field Description Offset Length
DEV_CLASS Identifies the device class to which this component belongs. 0 1
DEV_TYPE Identifies the specific device type within the device class. 1 1

CONFLICT_MSG message
Field Description Offset Length
DEV_CLASS Identifies the device class to which this component belongs. 0 1
DEV_TYPE Identifies the specific device type within the device class. 1 1

CHGI2C_MSG message
Field Description Offset Length
CUR_ADDR Components current I2C address.  Used to verify this is actually component message is actually intended for. 0 1
NEW_ADDR New 7-bit I2C address for component 1 1

Digital I/O messages

DIO_INTR message
Field Description Offset Length

DIO_TRIS message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port of this command.  The upper nibble indicates the number of consecutive ports this command addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1
PORT_STATE After PORT_RANGE, one byte is included for every port to be addressed by this command.  For each byte, a 0 bit indicates that the corresponding bit on the port is set for output, while a 1 indicates that the corresponding bit on the port is set for input. 1 number of ports configured

DIO_OUT message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port of this command.  The upper nibble indicates the number of consecutive ports this command addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1
PORT_DATA After PORT_RANGE, one byte is included fro every port to be addressed by this command.  Each byte is output to the appropriate port.  A 1 bit asserts the corresponding bit on the port, a 0 bit deasserts the corresponding bit on the port.  If a bit on the port is set for input, outputting to it has no affect. 1 Number of ports written

DIO_INREQ message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port to be read.  The upper nibble indicates the number of consecutive ports this read addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1

DIO_IN message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port to be read.  The upper nibble indicates the number of consecutive ports this read addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1
PORT_DATA After PORT_RANGE, one byte is included fro every port to be addressed by this command.  Each byte corresponds to the input from the corresponding port.  If a bit is 1, the corresponding bit on the port is reading high, if a bit is 0, the corresponding bit on the port is reading low.  If a bit on the port is setup as an output, the value it reads is meaningless and should be ignored. 1 Number of ports read

Analog input messages

AI_INTR message
Field Description Offset Length

AI_INREQ message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port to be read.  The upper nibble indicates the number of consecutive ports this read addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1

AI_IN message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port to be read.  The upper nibble indicates the number of consecutive ports this read addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1
ANALOG_DATA Following PORT_RANGE, 2 bytes are present for every port being read according to PORT_RANGE.  These two byte pairs are the value read off the A/D converter for the corresponding port, in big endian format. 0 2 * number of ports read

AI_VREF message
Field Description Offset Length
VREF VREF is a 2 byte, big endian value which is given to the D/A converter which supplies the Vref on selected analog components.  Outputting a value with higher resolution than the D/A converter supports will result in the data being truncated, sometimes in surprising ways.  The resolution of the Vref A/D converter can be determined from the CAPS_RESP information. 1 2

Analog output messages

AO_OUT message
Field Description Offset Length
PORT_RANGE The lower nibble of this byte indicates the starting port of this output.  The upper nibble indicates the number of consecutive ports this command addresses, 0 meaning only one port, 1 meaning two ports, etc.  For example, 0x01 indicates this command affects port 1 only, 0x13 indicates this command affects ports 3 and 4. 0 1
ANALOG_DATA Following PORT_RANGE, 2 bytes are present for every port being written according to PORT_RANGE. These two byte pairs are the value to be written to the D/A converter for the corresponding port, in big endian format. 1 2 * number of ports written

AO_VREF message
Field Description Offset Length
VREF VREF is a 2 byte, big endian value which is given to the D/A converter which supplies the Vref on selected analog components.  Outputting a value with higher resolution than the D/A converter supports will result in the data being truncated, sometimes in surprising ways.  The resolution of the Vref A/D converter can be determined from the CAPS_RESP information. 1 2

Stepper motor messages

SM_ROTATE message
Field Description Offset Length

Top

Component classes

This section describes the currently defined device classes for AKO components.

AKO component classes
Class ID Class name Description
0x00 Digital I/O All components whose interaction with the environment is in the form of digital signals.  This class includes such things as raw digital I/O components, proximity sensors, and so forth.
0x01 Analog input All components whose interaction with the environment is in the form of analog inputs.  This class includes such things as raw A/D converters, light intensity meters, temperature sensors, and so forth.
0x02 Analog output All components whose interaction with the environment is in the form of analog outputs.  This class includes such things as raw D/A converters, and so forth.
0x03 Stepper motor This class includes components which control stepper motors, such as the single stepper motor component and the mobile base unit (?).

Top

Component types

This section describes the component types for each component class for AKO components.

Digital I/O types
Type ID Type name Description
0x00 RAW_DIO Components which provide raw digital I/O lines to the user
0x01 PROXIMITY Components which provide a binary indication if an object is within a certain proximity

Analog input types
Type ID Type name Description
0x00 RAW_AI Components which provide raw analog input lines to the user
0x01 LIGHT Components which provide light intensity readings
0x02 TEMP Components which provide temperature readings

Analog output types
Type ID Type name Description
0x00 RAW_AO Components which provide raw analog output lines to the user

Stepper motor types
Type ID Type name Description
0x00 SM1 Components which allow the user to control a single stepper motor

Top

Procedures

This section describes procedures and rules AKO compliant components should follow.

Checksum calculation

The CHECKSUM field of an AKO packet, which is always the last byte of the packet, is calculated by finding the modulo-255 of all bytes in the packet preceding the CHECKSUM byte.

For instance, the checksum for the packet 0x07, 0x50, 0x42, 0x11, 0x01, 0x00, would be ((0x07 + 0x50 + 0x42 + 0x11 + 0x01 + 0x00) & 0xff) = 0xab.

The following code fragment illustrates proper checksum calculation.

    int j, LENGTH = 0, cksum = 0;
    int CHECKSUM = packet[LENGTH] - 1;

    for (j = 0; j < packet[LENGTH] - 1; j++) {
        cksum += packet[j];
    }
    packet[CHECKSUM] = cksum & 0xff;

Top

Pinging

To find out if a device with a particular I2C address is currently connected to the network, a device should follow the following ping procedure.  To ping a component, one should perform an I2C master transmit to the device being pinged that contains no data.  If the device is connected to the network, it will ACK it's I2C address.  Since components are allowed to ignore messages by not ACKing the data bytes of packet, this method allows pinging of devices which are currently not accepting packets. 
Ping procedure
  1. Assert START condition on I2C bus
  2. Send address being pinged
  3. Check for ACK from device to see if device is on network
  4. Assert STOP or repeated START condition on I2C bus
This ping procedure may be accomplished through the AKO I2C device driver by performing a zero byte write.
    device_present = !write(i2c_fd, some_buf, 0);

Top

Joining the network

When a device is preparing to join the network, it should first check that its joining the network will not create any I2C address conflicts.  It accomplishes this task by pinging it's own I2C address.  If there is no answer to the ping, then no device is using its I2C address on the network, and it is safe to join the network.  If there is a response to the ping, then joining the network would generate an I2C address conflict.  In this situation, the device should send a CONFLICT_MSG to the device manager, and then cease performing I2C network activities.
Psuedocode for joining the network
    assert START condition on I2C bus;
    send MY_I2C_ADDRESS;
    if (no ACK received) {
        /* no conflict detected */
        assert repeated START condition on I2C bus;
        send INIT_MSG to device manager;
        start I2C slave interface;
        assert STOP condition on I2C bus;
    } else {
        /* conflict detected! */
        assert repeated START condition on I2C bus;
        send CONFLICT_MSG to device manager;
        shut down I2C interface;
        assert STOP condition on I2C bus;
    }

Top

Sending unsolicited messages

When a component sends a message to the device manager that is not in response to a request message, the INVARIANT field of the message should contain 0x00.  This allows the device manager to distinguish between solicited and unsolicited messages.

Top

Immediate success protocol extension

The immediate success protocol extension allows the sender to receive immediate feedback as to whether or not an AKO packet was received error-free at the receiving end.  Since not all components may support this protocol extension, the send must check in advance if a particular component supports this extension by checking its CAPS_RESP.

To utilize this extension, the sender transmits a zero after transmitting all bytes in the AKO packet, but within the same I2C frame that the AKO packet was transmitted in.  If the receiver received all bytes of the packet, and the CHECKSUM on the packet is correct, the receiver will ACK the zero byte.  If an error was detected in the AKO packet by the receiver, the receiver will not ACK the zero byte.  This allows immediate feedback regarding the successful transmission of a packet.

Immediate success extension procedure
  1. Assert START condition on I2C bus
  2. Send receiver's address
  3. Send entire AKO packet
  4. Send 0x00
  5. Check for ACK from slave, ACK means success, no ACK means error
  6. Close I2C frame by asserting STOP or repeated START condition

Top

Top
Project AKO home