= 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. The following banks are defined: ||= Bit =||= Symbolic name =||= Description =|| ||0 ||DEVINFO ||Contains generic device informations || ||1 ||SYSCTL ||Contains system control data || ||2 ||GPDIO ||Contains data for General Purpose Digital Input/Output || ||3 ||GPAIO ||Contains data for Purpose Analog Input/Output ||63 ||DMX512 ||Contains universe buffer for DMX512 || ||64-95 ||TYPEST00-TYPEST31 ||Device type specific banks || ||96-127 ||VENDOR00-VENDOR31 ||Vendor and Device type specific banks || ||128-255 || ||Reserved. || === 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) }}}