decoders/uart/__init__.py

   1 ##
   2 ## This file is part of the sigrok project.
   3 ##
   4 ## Copyright (C) 2012 Uwe Hermann <uwe@hermann-uwe.de>
   5 ##
   6 ## This program is free software; you can redistribute it and/or modify
   7 ## it under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 2 of the License, or
   9 ## (at your option) any later version.
  10 ##
  11 ## This program is distributed in the hope that it will be useful,
  12 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ## GNU General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with this program; if not, write to the Free Software
  18 ## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19 ##
  20
  21 '''
  22 UART protocol decoder.
  23
  24 Universal Asynchronous Receiver Transmitter (UART) is a simple serial
  25 communication protocol which allows two devices to talk to each other.
  26
  27 It uses just two data signals and a ground (GND) signal:
  28  - RX/RXD: Receive signal
  29  - TX/TXD: Transmit signal
  30
  31 The protocol is asynchronous, i.e., there is no dedicated clock signal.
  32 Rather, both devices have to agree on a baudrate (number of bits to be
  33 transmitted per second) beforehand. Baudrates can be arbitrary in theory,
  34 but usually the choice is limited by the hardware UARTs that are used.
  35 Common values are 9600 or 115200.
  36
  37 The protocol allows full-duplex transmission, i.e. both devices can send
  38 data at the same time. However, unlike SPI (which is always full-duplex,
  39 i.e., each send operation is automatically also a receive operation), UART
  40 allows one-way communication, too. In such a case only one signal (and GND)
  41 is required.
  42
  43 The data is sent over the TX line in so-called 'frames', which consist of:
  44  - Exactly one start bit (always 0/low).
  45  - Between 5 and 9 data bits.
  46  - An (optional) parity bit.
  47  - One or more stop bit(s).
  48
  49 The idle state of the RX/TX line is 1/high. As the start bit is 0/low, the
  50 receiver can continually monitor its RX line for a falling edge, in order
  51 to detect the start bit.
  52
  53 Once detected, it can (due to the agreed-upon baudrate and thus the known
  54 width/duration of one UART bit) sample the state of the RX line "in the
  55 middle" of each (start/data/parity/stop) bit it wants to analyze.
  56
  57 It is configurable whether there is a parity bit in a frame, and if yes,
  58 which type of parity is used:
  59  - None: No parity bit is included.
  60  - Odd: The number of 1 bits in the data (and parity bit itself) is odd.
  61  - Even: The number of 1 bits in the data (and parity bit itself) is even.
  62  - Mark/one: The parity bit is always 1/high (also called 'mark state').
  63  - Space/zero: The parity bit is always 0/low (also called 'space state').
  64
  65 It is also configurable how many stop bits are to be used:
  66  - 1 stop bit (most common case)
  67  - 2 stop bits
  68  - 1.5 stop bits (i.e., one stop bit, but 1.5 times the UART bit width)
  69  - 0.5 stop bits (i.e., one stop bit, but 0.5 times the UART bit width)
  70
  71 The bit order of the 5-9 data bits is LSB-first.
  72
  73 Possible special cases:
  74  - One or both data lines could be inverted, which also means that the idle
  75    state of the signal line(s) is low instead of high.
  76  - Only the data bits on one or both data lines (and the parity bit) could
  77    be inverted (but the start/stop bits remain non-inverted).
  78  - The bit order could be MSB-first instead of LSB-first.
  79  - The baudrate could change in the middle of the communication. This only
  80    happens in very special cases, and can only work if both devices know
  81    to which baudrate they are to switch, and when.
  82  - Theoretically, the baudrate on RX and the one on TX could also be
  83    different, but that's a very obscure case and probably doesn't happen
  84    very often in practice.
  85
  86 Error conditions:
  87  - If there is a parity bit, but it doesn't match the expected parity,
  88    this is called a 'parity error'.
  89  - If there are no stop bit(s), that's called a 'frame error'.
  90
  91 More information:
  92 TODO: URLs
  93
  94 Protocol output format:
  95
  96 UART packet:
  97 [<packet-type>, <rxtx>, <packet-data>]
  98
  99 This is the list of <packet-types>s and their respective <packet-data>:
 100  - 'STARTBIT': The data is the (integer) value of the start bit (0 or 1).
 101  - 'DATA': The data is the (integer) value of the UART data. Valid values
 102    range from 0 to 512 (as the data can be up to 9 bits in size).
 103  - 'PARITYBIT': The data is the (integer) value of the parity bit (0 or 1).
 104  - 'STOPBIT': The data is the (integer) value of the stop bit (0 or 1).
 105  - 'INVALID STARTBIT': The data is the (integer) value of the start bit
 106    (0 or 1).
 107  - 'INVALID STOPBIT': The data is the (integer) value of the stop bit
 108    (0 or 1).
 109  - 'PARITY ERROR': The data is a tuple with two entries. The first one is
 110    the expected parity value, the second is the actual parity value.
 111  - TODO: Frame error?
 112
 113 The <rxtx> field is 0 for RX packets, 1 for TX packets.
 114 '''
 115
 116 from .uart import *
 117