Getting Started

Setting up a Build Environment

This guide highlights the installation / setup process for the LUNA gateware library. It focuses on getting the Python module (and prerequisites) up and running.

Prerequisites

  • Python 3.8, or later.

  • A working FPGA toolchain. We only officially support a toolchain composed of the Project Trellis ECP5 tools, the yosys synthesis suite, and the NextPNR place-and-route tool. You can obtain the latest binary distribution of this software from the oss-cad-suite-build project.

  • A working installation of Amaranth HDL.

Installation

Currently, the LUNA library is considered a “work-in-progress”; and thus it’s assumed you’ll want to use a local copy of LUNA for development.

# clone the LUNA repository
git clone https://github.com/greatscottgadgets/luna.git

The easiest way to set this up is to install the distribution in your working environment. From the root of the repository:

# Install a copy of our local tools.
pip install .

# Alternatively: install all dependencies,
# including optional development packages (required for running applets and examples).
pip install .[dev]

If you want to install LUNA to your machine globally (not recommended), you can do so using the following single command:

# Create a LUNA package, and install it.
pip install . --user

Testing

The easiest way to test your installation is to build one of the test applets. These applets are just Python scripts that construct and program gateware using Amaranth HDL; so they can be run like any other script:

# With GSG or self-built Cynthion hardware connected; we can test both our
# installation and the attached hardware.
python applets/bulk_speed_test.py

# Without hardware connected, we'll only build the applet, to exercise
# our toolchain.
python applets/bulk_speed_test.py --dry-run