[libsigrokdecode.git] / decoders / uart / __init__.py

##
## This file is part of the libsigrokdecode project.
##
## Copyright (C) 2012 Uwe Hermann <uwe@hermann-uwe.de>
##
## This program is free software; you can redistribute it and/or modify
## it under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 2 of the License, or
## (at your option) any later version.
##
## This program is distributed in the hope that it will be useful,
## but WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
##

'''
UART protocol decoder.

Universal Asynchronous Receiver Transmitter (UART) is a simple serial
communication protocol which allows two devices to talk to each other.

This decoder should work on all "UART-like" async protocols with one
start bit (0), 7-9 databits, an (optional) parity bit, and one or more
stop bits (1), in this order.

It can be run on one signal line (RX or TX) only, or on two lines (RX + TX).

There are various standards for the physical layer specification of the
signals, including RS232, (TTL) UART, RS485, and others. However, the logic
level of the respective pins is only relevant when acquiring the data via
a logic analyzer (you have to select the correct logic analyzer and/or
the correct place where to probe). Once the data is in digital form and
matches the "UART" description above, this protocol decoder can work with
it though, no matter whether the source was on TTL UART levels, or RS232,
or others.

Protocol output format:

UART packet:
[<packet-type>, <rxtx>, <packet-data>]

This is the list of <packet-type>s and their respective <packet-data>:
 - 'STARTBIT': The data is the (integer) value of the start bit (0/1).
 - 'DATA': The data is the (integer) value of the UART data. Valid values
   range from 0 to 512 (as the data can be up to 9 bits in size).
 - 'PARITYBIT': The data is the (integer) value of the parity bit (0/1).
 - 'STOPBIT': The data is the (integer) value of the stop bit (0 or 1).
 - 'INVALID STARTBIT': The data is the (integer) value of the start bit (0/1).
 - 'INVALID STOPBIT': The data is the (integer) value of the stop bit (0/1).
 - 'PARITY ERROR': The data is a tuple with two entries. The first one is
   the expected parity value, the second is the actual parity value.
 - TODO: Frame error?

The <rxtx> field is 0 for RX packets, 1 for TX packets.
'''

from .pd import *
Commit	Line	Data
64c29e28	1	##
50bd5d25	2	## This file is part of the libsigrokdecode project.
64c29e28 UH	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.
156509ca UH	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
3091f4e0 UH	27	This decoder should work on all "UART-like" async protocols with one
	28	start bit (0), 7-9 databits, an (optional) parity bit, and one or more
	29	stop bits (1), in this order.
	30
	31	It can be run on one signal line (RX or TX) only, or on two lines (RX + TX).
	32
	33	There are various standards for the physical layer specification of the
	34	signals, including RS232, (TTL) UART, RS485, and others. However, the logic
	35	level of the respective pins is only relevant when acquiring the data via
	36	a logic analyzer (you have to select the correct logic analyzer and/or
	37	the correct place where to probe). Once the data is in digital form and
	38	matches the "UART" description above, this protocol decoder can work with
	39	it though, no matter whether the source was on TTL UART levels, or RS232,
	40	or others.
8e828d2a UH	41
	42	Protocol output format:
	43
	44	UART packet:
	45	[<packet-type>, <rxtx>, <packet-data>]
	46
71077f34	47	This is the list of <packet-type>s and their respective <packet-data>:
1541976f	48	- 'STARTBIT': The data is the (integer) value of the start bit (0/1).
8e828d2a UH	49	- 'DATA': The data is the (integer) value of the UART data. Valid values
8e828d2a UH	50	range from 0 to 512 (as the data can be up to 9 bits in size).
1541976f	51	- 'PARITYBIT': The data is the (integer) value of the parity bit (0/1).
8e828d2a	52	- 'STOPBIT': The data is the (integer) value of the stop bit (0 or 1).
1541976f UH	53	- 'INVALID STARTBIT': The data is the (integer) value of the start bit (0/1).
1541976f UH	54	- 'INVALID STOPBIT': The data is the (integer) value of the stop bit (0/1).
8e828d2a UH	55	- 'PARITY ERROR': The data is a tuple with two entries. The first one is
	56	the expected parity value, the second is the actual parity value.
	57	- TODO: Frame error?
	58
	59	The <rxtx> field is 0 for RX packets, 1 for TX packets.
	60	'''
	61
24c74fd3	62	from .pd import *
64c29e28	63