]>
Commit | Line | Data |
---|---|---|
64c29e28 UH |
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 | ||
8e828d2a | 21 | ''' |
156509ca UH |
22 | UART protocol decoder. |
23 | ||
8e828d2a UH |
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 | ||
71077f34 | 99 | This is the list of <packet-type>s and their respective <packet-data>: |
1541976f | 100 | - 'STARTBIT': The data is the (integer) value of the start bit (0/1). |
8e828d2a UH |
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). | |
1541976f | 103 | - 'PARITYBIT': The data is the (integer) value of the parity bit (0/1). |
8e828d2a | 104 | - 'STOPBIT': The data is the (integer) value of the stop bit (0 or 1). |
1541976f UH |
105 | - 'INVALID STARTBIT': The data is the (integer) value of the start bit (0/1). |
106 | - 'INVALID STOPBIT': The data is the (integer) value of the stop bit (0/1). | |
8e828d2a UH |
107 | - 'PARITY ERROR': The data is a tuple with two entries. The first one is |
108 | the expected parity value, the second is the actual parity value. | |
109 | - TODO: Frame error? | |
110 | ||
111 | The <rxtx> field is 0 for RX packets, 1 for TX packets. | |
112 | ''' | |
113 | ||
24c74fd3 | 114 | from .pd import * |
64c29e28 | 115 |