wiki:Specs/I²C/Protocol

Version 8 (modified by ph3-der-loewe, 6 years ago) (diff)

+DMX512

Standard I²C Protocol for RoarAudio Devices

Overview

RoarAudio Devices with I²C interface provide a standard Memory interface on the bus. Communication with the device is done by reading and writing to memory cells. The Memory is organized into diffrent banks. Each bank is used to access a single command or feature.

The memory structure is as following:

Offset Description
0 Interface Version
1 Device Status
2 Command/Bank ID
3 Device Error
4 Bank data

Interface Version

This is the version of the Interface. This document describes version 0.

Device Status

This is a overall status byte.

Bit Description
0 Device Ready
1 Selfcheck passed
2 Selfcheck returned error
3 Updates since last read
4 Reserved
5 Reserved
6 Reserved
7 Reserved

If bit 1 and 2 is zero selfcheck is currently running. Bit 3 is set after value changes of ADC pins or GPI pins. It is reset when the correspdoning bank (holding the updated value) is selected.

Command/Bank ID

This is the ID of the selected memory bank.

Device Error

This is the device's error code. It is updated after every command/bank change and may be updated on writing command specific parameters. The values are standard RoarAudio Error Values. See Specs/ErrorValues

Bank 0: Device Info

The memory bank 0 holds general device information and status.

The structure is as following:

Offset Length Description
4 2 Device Status
6 1 Vendor ID
7 1 Device Type
8 1 Device Sub-Type
9 1 Device Revision
10 1 Parent Vendor ID
11 1 Parent Device Type
12 1 Parent Device Sub-Type
13 3 Device Capabilities
16 16 Device Serial

Vendor ID, Device Type, Device Sub-Type, Device Revision

Those are information on the vendor and kind of the device. The vendor ID is the actual vendor of the device. The device type is the basic type of the device:

Type Symbolic name Description
0 GENERIC This is a generic device. It only supports this Bank.
1 BRIDGE This device interacts as bridge between at least two different physical or logical ports.
2-63 Reserved.
64-127 VENDOR00 - VENDOR63 Vendor specific type. Depends on the Device Vendor.

The subtype defines the device more closely. The subtype fully depends on the type. However the value of zero should be used for the most basic kind of this type of device.

For devices of type GENERIC the subtype MUST be zero. For devices of type BRIDGE the following subtypes are defined:

Type Symbolic name Description
0 GENERIC Generic bridge device.
1 CONVERTER Device is a simple media converter.
2-255 Reserved.

The revision corresponds to the revision of the real hardware or firmware. This is mostly for informational usage but can also be used by a driver to detect the presents of an advanced feature added only to later devices of this type/subtype.

Parent Vendor ID, Parent Device Type, Parent Device Sub-Type

Those parameters work exactly as the Vendor, Type and Sub-Type parameters. They give information about the logical parent device type. The device has all attributes of the parent device in addition to it's own. The main usage of this is to allow writing drivers with some standard functionality. Those can check for the parent device attributes and use those to select a basic set of instructions how to talk to the device. This is important for Plug&Play and avoids that similar devices use completely incompatible modes of operation.

Device Status, Device Capabilities

Those parameters' meaning is depending on Device's Vendor ID, type and sub-type as well as parent device vendor ID, type and sub-type ID.

The GENERIC device defines that all the bits are used by the child device or set to zero. The BRIDGE device has the following Device Capabilities:

Bit Symbolic name Description
0 NETWORK Network of any kind is present
1 ETHERNET Ethernet is present
2 I2C I²C interface is present
3 SPI SPI port is present
4 DMX512 DMX512 port is present
5 MIDI MIDI port is present
6 WAVEFORM Waveform (Analog IO for equivalent spaces samples) port is present
7 RESERVED7 Reserved for future use.
8-23 Defined by subtype.

Device Serial

The serial of the device is given as a 16 byte bitstring. This is intended to be used to store an UUID as device serial. If a vendor uses some other numbering a schema neets to be established that maps those serials to the device serial field. A mapping should be chosen that complies with the current UUID standard.

Bank 63: DMX512

The DMX512 bank consists of two parts: the sub-bank part and the data part:

Offset Length Description
4 1 Subbank select
5-end till end Data

The subbank select is the offset of the DMX data as mapped into the bank. The channel of a given address is: (address-5)+32*subbank. This allows access to about eight thousand channels, or sixteen universes.

A typical method to randomly access channels is:

 variables of unsigned integer type: bank, offset

 bank = int(channel/32)
 offset = bank*32

 write_to_device(OFFSET_SUBBANK, bank)
 write_to_device(OFFSET_DATA+channel-offset, value)