Skip to content

Bring the docs back to life #260

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cbespin merged 4 commits into from
Mar 26, 2026
Merged

Bring the docs back to life #260

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fee494f
docs: update and fix documentation
kcaisley Mar 24, 2026
4246286
docs: fix dead links, add YAML reference, improve styling
kcaisley Mar 24, 2026
53d6c51
docs: Address feedback in pull request, update diagram
kcaisley Mar 26, 2026
4eefb4f
fix: X-ray sources aren't bathtubs
kcaisley Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ var/
*.egg-info/
.installed.cfg
*.egg
uv.lock
.venv/

# icarus verilog
host/tests/Makefile
Expand Down
15 changes: 15 additions & 0 deletions .readthedocs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
version: 2

build:
os: ubuntu-lts-latest
tools:
python: "3.12"

sphinx:
configuration: docs/conf.py

python:
install:
- requirements: docs/requirements.txt
- method: pip
path: .
41 changes: 16 additions & 25 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,7 @@ Basil
:target: http://basil.rtfd.org
:alt: Documentation

Basil is a modular data acquisition system and system testing framework in Python.

It also provides generic FPGA firmware modules for different hardware platforms and drivers for wide range of lab appliances.
Basil is a modular data acquisition (DAQ) framework developed by `SiLab <https://silab-bonn.github.io/>`_ for the characterization of `monolithic <https://en.wikipedia.org/wiki/Monolithic_active_pixel_sensor>`_ and `hybrid <https://en.wikipedia.org/wiki/Hybrid_pixel_detector>`_ pixel detectors. It comprises a library of HDL modules (written in Verilog) for custom FPGA readout boards, paired with a collection of Python code that control the hardware over USB, Ethernet, or serial interfaces from a host PC. Basil also includes Python drivers for common lab instruments such as power supplies, oscilloscopes, and other bench equipment.

Features
========
Expand All @@ -26,36 +24,28 @@ Software:
- layer structure following hardware
- generation based on yaml file
- register abstract layer (RAL)
- simulator interface allows software test against simulated RTL (thanks to `cocotb <https://github.com/potentialventures/cocotb>`_)
- simulator interface allows software test against simulated RTL (thanks to `cocotb <https://github.com/cocotb/cocotb>`_)

Installation
============

Clone the repository to get a copy of the source code (for developers):
Install via PyPI:

.. code-block:: bash

git clone https://github.com/SiLab-Bonn/basil.git
cd basil
pip install -e .

or install via PyPI into the Python's site-packages folder (for non-developers):

.. code-block:: bash
pip install basil-daq

pip install basil_daq==version
.. note::

where version is a version number (e.g., 3.0.1)
The PyPI package may be outdated. Installing from source (below) is recommended to get the latest version.

or install from git, when no PyPI package is available (for non-developers):
Or install from source:

.. code-block:: bash

pip install git+https://github.com/SiLab-Bonn/basil.git@branch

where branch is a branch name or tag (e.g., master or v3.0.1).

Check `.travis.yml <.travis.yml>`_ for installation/testing hints.
git clone https://github.com/SiLab-Bonn/basil.git
cd basil
pip install -e .

Support
=======
Expand All @@ -69,11 +59,12 @@ Documentation

Documentation can be found under: https://basil.rtfd.org

Example Projects:
=================
- `pyBAR <https://github.com/SiLab-Bonn/pyBAR>`_ - Bonn ATLAS Readout in Python
- `MCA <https://github.com/SiLab-Bonn/MCA>`_ - Multi Channel Analyzer
- `fe65_p2 <https://github.com/SiLab-Bonn/fe65_p2>`_ - DAQ for FE65P2 prototype
Example Projects
================
- `TJ-Monopix2 <https://github.com/SiLab-Bonn/tj-monopix2-daq>`_ - DAQ for TJ-Monopix2 depleted monolithic pixel sensor
- `BDAQ53 <https://gitlab.cern.ch/silab/bdaq53>`_ - Readout system for ATLAS ITkPix (RD53) chips
- `LF-Monopix2 <https://github.com/SiLab-Bonn/lf-monopix2-daq>`_ - DAQ for LF-Monopix2 depleted monolithic pixel sensor
- `FRIDA <https://github.com/kcaisley/frida>`_ - DAQ for FRIDA, an ADC test array for frame-based imaging detectors

License
=======
Expand Down
3 changes: 1 addition & 2 deletions basil/HL/i2c.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,7 @@ def is_done(self):
@property
def is_ready(self):
'''
:raises ExceptionType: IOError
Transfer not acknowledged.
:raises IOError: Transfer not acknowledged.
'''
if self.NO_ACK:
raise IOError('i2c:Transfer not acknowledged')
Expand Down
90 changes: 45 additions & 45 deletions basil/firmware/modules/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,48 +4,48 @@ Basil modules

.. begin-include

Modules use simple bus single master interconnection bus.
Every module has same/similar set of parameters and pins that allow to properly connect to bus.

Full list of modules can be found in `firmware/modules folder <https://github.com/SiLab-Bonn/basil/tree/master/firmware/modules>`_.

Software drivers for modules can be found in `basil/HL folder <https://github.com/SiLab-Bonn/basil/tree/master/basil/HL>`_.

Parameters
+--------------+---------------------+--------------------------------------------------------------------+
| Name | Default | Description |
+==============+=====================+====================================================================+
| BASEADDR | 0 | Defines base address of module (start address) in memory map space |
+--------------+---------------------+--------------------------------------------------------------------+
| HIGHADDR | 0 | Defines last module address in memory map space |
+--------------+---------------------+--------------------------------------------------------------------+
| ABUSWIDTH | 16 | Define address bus with |
+--------------+---------------------+--------------------------------------------------------------------+
| DBUSWIDTH | 8 | Define data bus with |
+--------------+---------------------+--------------------------------------------------------------------+

Pins
+--------------+-------------------------+-----------+------------------------------------------------------+
| Name | Size | Direction | Description |
+==============+=========================+===========+======================================================+
| BUS_RST | 1 | input | Synchronous Reset - Active High |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_CLK | 1 | input | Clock |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_WR | 1 | input | Write strobe - Active High |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_RD | 1 | input | Read strobe - Active High |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_ADD | ABUSWIDTH | input | Address bus` |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_DATA | DBUSWIDTH (typically 8) | inout | Data Bus |
+--------------+-------------------------+-----------+------------------------------------------------------+

Registers
+------------+----------------+-------+----------------------------------------+
| Name | Address | r/w | Description |
+============+================+=======+========================================+
| RESET | 0 | wo | Soft reset active on write to address |
+------------+----------------+-------+----------------------------------------+
| VERSION | 0 | ro | Module version |
+------------+----------------+-------+----------------------------------------+
Modules connect to a simple single-master bus. Every module has a similar set of parameters and pins for bus integration. The full list of firmware modules can be found in the `firmware/modules <https://github.com/SiLab-Bonn/basil/tree/master/basil/firmware/modules>`_ folder, and their Python drivers in `basil/HL <https://github.com/SiLab-Bonn/basil/tree/master/basil/HL>`_.

The following parameters, pins, and registers are common to all bus-connected modules. Individual modules add their own on top of these.

**Common parameters:**

+--------------+---------------------+--------------------------------------------------------------------+
| Name | Default | Description |
+==============+=====================+====================================================================+
| BASEADDR | 0 | Defines base address of module (start address) in memory map space |
+--------------+---------------------+--------------------------------------------------------------------+
| HIGHADDR | 0 | Defines last module address in memory map space |
+--------------+---------------------+--------------------------------------------------------------------+
| ABUSWIDTH | 16 | Address bus width |
+--------------+---------------------+--------------------------------------------------------------------+
| DBUSWIDTH | 8 | Data bus width |
+--------------+---------------------+--------------------------------------------------------------------+

**Common pins:**

+--------------+-------------------------+-----------+------------------------------------------------------+
| Name | Size | Direction | Description |
+==============+=========================+===========+======================================================+
| BUS_RST | 1 | input | Synchronous reset, active high |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_CLK | 1 | input | Bus clock |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_WR | 1 | input | Write strobe, active high |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_RD | 1 | input | Read strobe, active high |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_ADD | ABUSWIDTH | input | Address bus |
+--------------+-------------------------+-----------+------------------------------------------------------+
| BUS_DATA | DBUSWIDTH | inout | Data bus |
+--------------+-------------------------+-----------+------------------------------------------------------+

**Common registers:**

+------------+----------------+-------+----------------------------------------+
| Name | Address | r/w | Description |
+============+================+=======+========================================+
| RESET | 0 | wo | Soft reset on write to address |
+------------+----------------+-------+----------------------------------------+
| VERSION | 0 | ro | Module version |
+------------+----------------+-------+----------------------------------------+
6 changes: 3 additions & 3 deletions basil/firmware/modules/cmd_seq/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@

=====================================
**cmd_seq** - cmd generator (FE-I4)
=====================================
=========================================
**cmd_seq** - Command generator (FE-I4)
=========================================

Generate arbitrary single bit data stream and clock (mainly to generate FE-I4 commands). Supports hardware loops and Manchester data encoding.

2 changes: 1 addition & 1 deletion basil/firmware/modules/fast_spi_rx/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

=====================================
**fast_spi_rx** - fast spi receiver
**fast_spi_rx** - Fast SPI receiver
=====================================

Allows continuous serial data receive. Received data are propagated to FIFO data interface.
8 changes: 4 additions & 4 deletions basil/firmware/modules/gpio/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

=============================
**gpio** - general purpose io
**gpio** - General purpose IO
=============================

General purpose input output (gpio) is a generic pins whose behavior, including whether it is an input or output pin, can be controlled by the user at run time.
Expand All @@ -9,7 +9,7 @@ General purpose input output (gpio) is a generic pins whose behavior, including
`test_SimGpio.v <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimGpio.v>`_
`test_SimGpio.py <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimGpio.py>`_

Parameters
**Parameters:**
+--------------+---------------------+-----------------------------------------------------------------+
| Name | Default | Description |
+==============+=====================+=================================================================+
Expand All @@ -20,14 +20,14 @@ Parameters
| IO_TRI | 0 | instantiate tri-state buffer for given pin |
+--------------+---------------------+-----------------------------------------------------------------+

Pins
**Pins:**
+--------------+---------------------+-----------------------+-----------------------------------------+
| Name | Size | Direction | Description |
+==============+=====================+=================================================================+
| IO | IO_WIDTH | IO_DIRECTION/IO_TRI | General purpose pins |
+--------------+---------------------+-----------------------------------------------------------------+

Registers
**Registers:**
+------------+---------------------+----------------------------------------+
| Name | Address | Description |
+============+=====================+========================================+
Expand Down
8 changes: 4 additions & 4 deletions basil/firmware/modules/i2c/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

======================================
**i2c** - i2c peripheral interface
**i2c** - I2C peripheral interface
======================================

Module implements master i2c peripheral interface.
Expand All @@ -9,14 +9,14 @@ Module implements master i2c peripheral interface.
`test_SimI2c.v <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimI2c.v>`_
`test_SimI2c.py <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimI2c.py>`_

Parameters
**Parameters:**
+--------------+---------------------+---------------------------------------------------------------------------------+
| Name | Default | Description |
+==============+=====================+=================================================================================+
| MEM_BYTES | 16 | Amount of memory (bytes) allocated for data (maximum single transfer in bytes) |
+--------------+---------------------+---------------------------------------------------------------------------------+

Pins
**Pins:**
+--------------+---------------------+-----------------------+---------------------------------------------------------+
| Name | Size | Direction | Description |
+==============+=====================+=======================+=========================================================+
Expand All @@ -27,7 +27,7 @@ Pins
| I2C_SCL | 1 | inout | SCL |
+--------------+---------------------+-----------------------+---------------------------------------------------------+

Registers
**Registers:**
+--------------+----------------------------------+--------+-------+-------------+---------------------------------------------+
| Name | Address | Bits | r/w | Default | Description |
+==============+==================================+========+=======+=============+=============================================+
Expand Down
8 changes: 4 additions & 4 deletions basil/firmware/modules/jtag_master/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@

======================================
**jtag** - serial peripheral interface
**jtag** - JTAG master
======================================

Module implements master jtag peripheral interface. Supports simple internal loops.
Expand All @@ -9,14 +9,14 @@ Module implements master jtag peripheral interface. Supports simple internal loo
`test_SimJtagMaster.v <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimJtagMaster.v>`_
`test_SimJtagMaster.py <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimJtagMaster.py>`_

Parameters
**Parameters:**
+--------------+---------------------+-------------------------------------------------------------------------+
| Name | Default | Description |
+==============+=====================+=========================================================================+
| MEM_BYTES | 16 | Amount of meemory allocated for data (maximum single transfer in bytes) |
+--------------+---------------------+-------------------------------------------------------------------------+

Pins
**Pins:**
+--------------+---------------------+-----------------------+------------------------------------------------------+
| Name | Size | Direction | Description |
+==============+=====================+=======================+======================================================+
Expand All @@ -35,7 +35,7 @@ Pins
| SLD | 1 | output | active high strobe indicating end of transfer |
+--------------+---------------------+-----------------------+------------------------------------------------------+

Registers
**Registers:**
+--------------+-----------------------------------+--------+-------+-------------+---------------------------------------------------------+
| Name | Address | Bits | r/w | Default | Description |
+==============+===================================+========+=======+=============+=========================================================+
Expand Down
Loading
Loading