Skip to content

Latest commit

 

History

History
117 lines (86 loc) · 5.64 KB

MessageSpecification.md

File metadata and controls

117 lines (86 loc) · 5.64 KB
Raw

Audio transmission protocol definition

This document describes the communication between the blinkenrocket and the audio generating device attached to it. It relies on the implementation of the tagsu-avr-modem for low-level communication.

The communication relies on multiple components:

START

A START signal which indicates the start of a transmission. It consists of two times a specific 8-bit binary pattern ( 10011001 respectively 0x99).

PATTERN

A PATTERN signal which indicates that either the start of an animation or text pattern. It consists of two times the 8-bit binary pattern ( 10101001 respectively 0xA9)

END

The END signal indicates End Of Transmission. It consists of two times the 8-bit binary pattern 10000100 respectively 0x84.

HEADER

A generic HEADER which contains two byte of metadata to describe the data that follows. The two byte contain 12 bit of length information and 4 bit of data type information.

XXXXYYYY YYYYYYYY
<-->
    <----------->
TYPE    LENGTH

Thus the data length can be up to 4kByte of data (4096 byte). A type of 0001 denotes a TEXT type pattern, a type 0010 denotes an ANIMATION type pattern. The modem only receives data for this pattern until length is exceeded. E.g. when a HEADER with the contents 00011111 11111111 is received by the modem it will read 4098 byte for the current pattern (2 byte header, 4096 byte of data). The maximum length for texts is 4096 characters and 512 frames for animation.

TEXT METADATA

A TEXTMETA is a two byte (16 bit) length metadata field for text type pattern. It encodes the speed (first nibble), the delay (second nibble) and the direction (third nibble). The fourth nibble is reserved for future use.

XXXX XXXX XXXX XXXX (MSB -> LSB)
---- (speed)
     ---- (delay)
          ---- (direction)
               ---- (reserved)

The speed and delay ranges from a numeric value from 0 (0000) to 15 (1111). The higher the number, the faster the speed and the longer the delay. A direction of 0 (0000) specifies a left direction, a direction of 1 (0001) specifies a right direction.

The scroll rate is about 1 / (0.5 - (0.032 * speed)) columns per second (or, precisely, 1 / (0.002048 * (250 - (16 * speed))) columns per second). This means that it can range from about 2 columns per second (speed=0) to almost 49 columns per second (speed=15). Note that it is not a linear function -- see the following speed <-> columns per second translation list for details:

  • speed = 0 : 1.95 cps
  • speed = 1 : 2.09 cps
  • speed = 2 : 2.24 cps
  • speed = 3 : 2.42 cps
  • speed = 4 : 2.63 cps
  • speed = 5 : 2.87 cps
  • speed = 6 : 3.17 cps
  • speed = 7 : 3.54 cps
  • speed = 8 : 4.00 cps
  • speed = 9 : 4.61 cps
  • speed = 10 : 5.43 cps
  • speed = 11 : 6.60 cps
  • speed = 12 : 8.42 cps
  • speed = 13 : 11.6 cps
  • speed = 14 : 18.8 cps
  • speed = 15 : 48.8 cps

The delay takes 0.5 * delay seconds.

ANIMATION METADATA

A ANIMMETA is a two byte (16 bit) length metadata field for animation type pattern. It encodes the frame rate in the lower nibble of the first byte and the delay in the lower nibble of the second byte.

0000XXXX 0000XXXX
<------> <------>
 SPEED     DELAY

The speed and delay ranges from a numeric value from 0 (0000) to 15 (1111) and are calculated as described in TEXT METADATA (except that the speed now refers to frames per second).

Message format

The message transmitted has to follow the following diagram:

       +--------------------------------------------------------+
       |                                                        |
       |                                         +--------+     |
       |                                         v        |     |
       |                         +--> TEXTMETA +--> DATA -+--+  |
       v                         |                           |  |
START +--> PATTERN +--> HEADER +-|                           +---> END
                                 |                           |
                                 +--> ANIMMETA +--> DATA -+--+
                                                 ^        |
                                                 +--------+

First there is a START signal to indicate that the transmission is about to start. This should initialize the internal state machine. After that a PATTERN indicator follows to indicate that a pattern is following. This is followed by the generic HEADER to set the size and type of the following data. Now depending on the type of the transmission there is either (XOR) the TEXTMETA or ANIMMETA fields followed by DATA fields that may repeat up to the length specified in the HEADER. After this the transmission either encounters an END or a repetition of the sequence starting with PATTERN.

Important note: the length of the data must be even (e.g. length(data) % 2 == 0) to make the Hamming(24,16) error correction work properly.

Error detection and correction

The error correction is performed using the Hamming-Code. For this application the Hamming(24,16) code is used, which contains 2 bytes of data with a ECC of 1 byte. The error correction is capabable of correcting up to two bit flips, which should be sufficient for this application.

XXXXXXXX YYYYYYYY EEEEEEEE
-------- -------- --------
 First    Second   Hamming

The encoding of the Hamming code is performed using this (click me) avr-specific library and this particular implementation optimized for speed and code footprint.