X-Git-Url: https://sigrok.org/gitweb/?p=libsigrokdecode.git;a=blobdiff_plain;f=decoders%2Fuart.py;h=dac7017cbcbe68d14be74a112db82b5adb402c55;hp=ee39697183618a5448be80dd92adbe6f02df217d;hb=0ee4dd54ce134158cd2068866ddc7d32c692d457;hpb=f44d2db2a027857bdfbfc18e40b9900cad1b0e1d diff --git a/decoders/uart.py b/decoders/uart.py index ee39697..dac7017 100644 --- a/decoders/uart.py +++ b/decoders/uart.py @@ -22,7 +22,79 @@ # UART protocol decoder # -import sigrok +# +# Universal Asynchronous Receiver Transmitter (UART) is a simple serial +# communication protocol which allows two devices to talk to each other. +# +# It uses just two data signals and a ground (GND) signal: +# - RX/RXD: Receive signal +# - TX/TXD: Transmit signal +# +# The protocol is asynchronous, i.e., there is no dedicated clock signal. +# Rather, both devices have to agree on a baudrate (number of bits to be +# transmitted per second) beforehand. Baudrates can be arbitrary in theory, +# but usually the choice is limited by the hardware UARTs that are used. +# Common values are 9600 or 115200. +# +# The protocol allows full-duplex transmission, i.e. both devices can send +# data at the same time. However, unlike SPI (which is always full-duplex, +# i.e., each send operation is automatically also a receive operation), UART +# allows one-way communication, too. In such a case only one signal (and GND) +# is required. +# +# The data is sent over the TX line in so-called 'frames', which consist of: +# - Exactly one start bit (always 0/low). +# - Between 5 and 9 data bits. +# - An (optional) parity bit. +# - One or more stop bit(s). +# +# The idle state of the RX/TX line is 1/high. As the start bit is 0/low, the +# receiver can continually monitor its RX line for a falling edge, in order +# to detect the start bit. +# +# Once detected, it can (due to the agreed-upon baudrate and thus the known +# width/duration of one UART bit) sample the state of the RX line "in the +# middle" of each (start/data/parity/stop) bit it wants to analyze. +# +# It is configurable whether there is a parity bit in a frame, and if yes, +# which type of parity is used: +# - None: No parity bit is included. +# - Odd: The number of 1 bits in the data (and parity bit itself) is odd. +# - Even: The number of 1 bits in the data (and parity bit itself) is even. +# - Mark/one: The parity bit is always 1/high (also called 'mark state'). +# - Space/zero: The parity bit is always 0/low (also called 'space state'). +# +# It is also configurable how many stop bits are to be used: +# - 1 stop bit (most common case) +# - 2 stop bits +# - 1.5 stop bits (i.e., one stop bit, but 1.5 times the UART bit width) +# - 0.5 stop bits (i.e., one stop bit, but 0.5 times the UART bit width) +# +# The bit order of the 5-9 data bits is LSB-first. +# +# Possible special cases: +# - One or both data lines could be inverted, which also means that the idle +# state of the signal line(s) is low instead of high. +# - Only the data bits on one or both data lines (and the parity bit) could +# be inverted (but the start/stop bits remain non-inverted). +# - The bit order could be MSB-first instead of LSB-first. +# - The baudrate could change in the middle of the communication. This only +# happens in very special cases, and can only work if both devices know +# to which baudrate they are to switch, and when. +# - Theoretically, the baudrate on RX and the one on TX could also be +# different, but that's a very obscure case and probably doesn't happen +# very often in practice. +# +# Error conditions: +# - If there is a parity bit, but it doesn't match the expected parity, +# this is called a 'parity error'. +# - If there are no stop bit(s), that's called a 'frame error'. +# +# More information: +# TODO: URLs +# + +import sigrokdecode # States WAIT_FOR_START_BIT = 0 @@ -55,17 +127,6 @@ DATA_FORMAT_HEX = 1 # TODO: Remove me later. quick_hack = 1 -class Sample(): - def __init__(self, data): - self.data = data - def probe(self, probe): - s = ord(self.data[probe / 8]) & (1 << (probe % 8)) - return True if s else False - -def sampleiter(data, unitsize): - for i in range(0, len(data), unitsize): - yield(Sample(data[i:i+unitsize])) - # Given a parity type to check (odd, even, zero, one), the value of the # parity bit, the value of the data, and the length of the data (5-9 bits, # usually 8 bits) return True if the parity is correct, False otherwise. @@ -89,7 +150,7 @@ def parity_ok(parity_type, parity_bit, data, num_data_bits): else: raise Exception('Invalid parity type: %d' % parity_type) -class Decoder(sigrok.Decoder): +class Decoder(sigrokdecode.Decoder): id = 'uart' name = 'UART' longname = 'Universal Asynchronous Receiver/Transmitter (UART)' @@ -100,14 +161,12 @@ class Decoder(sigrok.Decoder): license = 'gplv2+' inputs = ['logic'] outputs = ['uart'] - probes = { + probes = [ # Allow specifying only one of the signals, e.g. if only one data # direction exists (or is relevant). - ## 'rx': {'ch': 0, 'name': 'RX', 'desc': 'UART receive line'}, - ## 'tx': {'ch': 1, 'name': 'TX', 'desc': 'UART transmit line'}, - 'rx': 0, - 'tx': 1, - } + {'id': 'rx', 'name': 'RX', 'desc': 'UART receive line'}, + {'id': 'tx', 'name': 'TX', 'desc': 'UART transmit line'}, + ] options = { 'baudrate': ['UART baud rate', 115200], 'num_data_bits': ['Data bits', 8], # Valid: 5-9. @@ -121,7 +180,8 @@ class Decoder(sigrok.Decoder): } def __init__(self, **kwargs): - self.probes = Decoder.probes.copy() + self.output_protocol = None + self.output_annotation = None # Set defaults, can be overridden in 'start'. self.baudrate = 115200 @@ -143,18 +203,13 @@ class Decoder(sigrok.Decoder): # Initial state. self.staterx = WAIT_FOR_START_BIT - # Get the channel/probe number of the RX/TX signals. - ## self.rx_bit = self.probes['rx']['ch'] - ## self.tx_bit = self.probes['tx']['ch'] - self.rx_bit = self.probes['rx'] - self.tx_bit = self.probes['tx'] - self.oldrx = None self.oldtx = None def start(self, metadata): - self.unitsize = metadata['unitsize'] self.samplerate = metadata['samplerate'] + # self.output_protocol = self.output_new(2) + self.output_annotation = self.output_new(1) # TODO ### self.baudrate = metadata['baudrate'] @@ -298,9 +353,7 @@ class Decoder(sigrok.Decoder): # TODO: Currently only supports 1 stop bit. def get_stop_bits(self, signal): # Skip samples until we're in the middle of the stop bit(s). - skip_parity = 0 - if self.parity != PARITY_NONE: - skip_parity = 1 + skip_parity = 0 if self.parity == PARITY_NONE else 1 if not self.reached_bit(self.num_data_bits + 1 + skip_parity): return [] @@ -320,15 +373,11 @@ class Decoder(sigrok.Decoder): 'data': None, 'ann': 'Stop bit'}] return o - def decode(self, data): - """UART protocol decoder""" - + def decode(self, timeoffset, duration, data): # TODO out = [] - for sample in sampleiter(data["data"], self.unitsize): - - # TODO: Eliminate the need for ord(). - s = ord(sample.data) + # for (samplenum, (rx, tx)) in data: + for (samplenum, (rx,)) in data: # TODO: Start counting at 0 or 1? Increase before or after? self.samplenum += 1 @@ -336,14 +385,10 @@ class Decoder(sigrok.Decoder): # First sample: Save RX/TX value. if self.oldrx == None: # Get RX/TX bit values (0/1 for low/high) of the first sample. - self.oldrx = (s & (1 << self.rx_bit)) >> self.rx_bit - # self.oldtx = (s & (1 << self.tx_bit)) >> self.tx_bit + self.oldrx = rx + # self.oldtx = tx continue - # Get RX/TX bit values (0/1 for low/high). - rx = (s & (1 << self.rx_bit)) >> self.rx_bit - # tx = (s & (1 << self.tx_bit)) >> self.tx_bit - # State machine. if self.staterx == WAIT_FOR_START_BIT: self.wait_for_start_bit(self.oldrx, rx) @@ -363,5 +408,6 @@ class Decoder(sigrok.Decoder): # self.oldtx = tx if out != []: - self.put(out) + # self.put(0, 0, self.output_protocol, out_proto) + self.put(0, 0, self.output_annotation, out)