Metadata-Version: 2.1
Name: cocotbext-uart
Version: 0.1.2
Summary: UART modules for cocotb
Home-page: https://github.com/alexforencich/cocotbext-uart
Author: Alex Forencich
Author-email: alex@alexforencich.com
License: MIT
Download-URL: https://github.com/alexforencich/cocotbext-uart/tarball/master
Project-URL: Bug Tracker, https://github.com/alexforencich/cocotbext-uart/issues
Project-URL: Source Code, https://github.com/alexforencich/cocotbext-uart
Keywords: uart,cocotb
Platform: any
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: cocotb
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cocotb
Provides-Extra: test
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: cocotb-test ; extra == 'test'

# UART interface modules for Cocotb

[![Build Status](https://github.com/alexforencich/cocotbext-uart/workflows/Regression%20Tests/badge.svg?branch=master)](https://github.com/alexforencich/cocotbext-uart/actions/)
[![codecov](https://codecov.io/gh/alexforencich/cocotbext-uart/branch/master/graph/badge.svg)](https://codecov.io/gh/alexforencich/cocotbext-uart)
[![PyPI version](https://badge.fury.io/py/cocotbext-uart.svg)](https://pypi.org/project/cocotbext-uart)

GitHub repository: https://github.com/alexforencich/cocotbext-uart

## Introduction

UART simulation models for [cocotb](https://github.com/cocotb/cocotb).

## Installation

Installation from pip (release version, stable):

    $ pip install cocotbext-uart

Installation from git (latest development version, potentially unstable):

    $ pip install https://github.com/alexforencich/cocotbext-uart/archive/master.zip

Installation for active development:

    $ git clone https://github.com/alexforencich/cocotbext-uart
    $ pip install -e cocotbext-uart

## Documentation and usage examples

See the `tests` directory and [verilog-uart](https://github.com/alexforencich/verilog-uart) for complete testbenches using these modules.

### UART

The `UartSource` and `UartSink` classes can be used to drive, receive, and monitor asynchronous serial data.

To use these modules, import the one you need and connect it to the DUT:

    from cocotbext.uart import UartSource, UartSink

    uart_source = UartSource(dut.rxd, baud=115200, bits=8)
    uart_sink = UartSink(dut.rxd, baud=115200, bits=8)

To send data into a design with a `UartSource`, call `write()` or `write_nowait()`.  Accepted data types are iterables of ints, including lists, bytes, bytearrays, etc.  Optionally, call `wait()` to wait for the transmit operation to complete.  Example:

    await uart_source.send(b'test data')
    # wait for operation to complete (optional)
    await uart_source.wait()

To receive data with a `UartSink`, call `read()` or `read_nowait()`.  Optionally call `wait()` to wait for new receive data.  `read()` will block until at least 1 data byte is available.  Both `read()` and `read_nowait()` will return up to _count_ bytes from the receive queue, or the entire contents of the receive queue if not specified.

    data = await uart_sink.recv()

#### Constructor parameters:

* _data_: data signal
* _baud_: baud rate in bits per second (optional, default 9600)
* _bits_: bits per byte (optional, default 8)
* _stop_bits_: length of stop bit in bit times (optional, default 1)

#### Attributes:

* _baud_: baud rate in bits per second
* _bits_: bits per byte
* _stop_bits_: length of stop bit in bit times

#### Methods

* `write(data)`: send _data_ (blocking) (source)
* `write_nowait(data)`: send _data_ (non-blocking) (source)
* `read(count)`: read _count_ bytes from buffer (blocking) (sink)
* `read_nowait(count)`: read _count_ bytes from buffer (non-blocking) (sink)
* `count()`: returns the number of items in the queue (all)
* `empty()`: returns _True_ if the queue is empty (all)
* `idle()`: returns _True_ if no transfer is in progress (all) or if the queue is not empty (source)
* `clear()`: drop all data in queue (all)
* `wait()`: wait for idle (source)
* `wait(timeout=0, timeout_unit='ns')`: wait for data received (sink)


