Neopixelar - the FPGA project

This project demonstrates the use of LiteX & migen to create a Neopixel driving FPGA based h/w unit, called NPE ('neopixel engine'). The project requires a colorlight-5a-75b board (sells at ~18€ as of 10/2020). A RISC-V CPU (RV32I) is incorporated as well as network RAM loading (2 banks!) & separate application flashing capability (MUCH faster, bringing flashboot to life!). The project also makes use of LiteDRAM DMA capabilities.

(Hint: project has been tested on Linux Mint 20 only, but should run on other Linux versions as well ...)

Installation

1. Software

To use this project effectively, you will have to install LiteX, see https://github.com/enjoy-digital/litex for details (and project Trellis, NextPNR & YoSys requirements). Also, it is recommended to install the board support, see https://github.com/litex-hub/litex-boards, as well as the the RISC-V tool chain (see https://github.com/sifive/freedom-tools/releases). To communicate with your board via network, install the wishbone tools, see https://github.com/litex-hub/wishbone-utils.

To use the automatic documentation feature, you will have to install sphinx, see https://www.sphinx-doc.org/en/master. Also its wavedrom extension has to be installed, see https://pypi.org/project/wavedrom. Some helpful links for RST docstring formats: http://daouzli.com/blog/docstring.html & https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

The project assumes a local 'fpga' path within the home directory of the user, where all the above mentioned software packages are installed. Furthermore, the project assumes a virtual environment named 'fpga' where all project relevant python libs are registered (this is not strictly necessary ... maybe software/ramcreate.sh has to be adjusted, as well as the python interpreter settings within VSC!). The actual 'Neopixelar' project may be installed anywhere, but local paths will have to be adjusted (firmware/main.c, software/ramcreate.sh ... worx for me ;).

2. Hardware

A JTAG programmer will be required for successful device programming. Thanx to Wolfgang, I'm using the Versaloon (s/w for blue-pill STM32), see https://github.com/zoobab/versaloon. To use this device, you also will have to install openocd via 'apt install openocd'. See https://git.hacknology.de/wolfgang/colorlight#user-content-class-hub75sender for details, on how to connect the JTAG adapter.

For board specific details see
https://github.com/enjoy-digital/colorlite/blob/master. Other helpful links to board data:
https://github.com/q3k/chubby75/blob/master/5a-75b/hardware_V7.0.md
https://saturn.ffzg.hr/rot13/index.cgi?colorlight_5a_75b
https://github.com/trabucayre/litexOnColorlightLab004/
https://blog.pcbxprt.com/index.php/2020/07/19/running-risc-v-core-on-small-fpga-board/

Program structure:

1. Neopixelar.py - this is the main FPGA building source
2. neopixelengine.py - this is the actual NeoPixel driving engine
3. libmodules subdir - DRAM DMA loader helper & system time support
4. helpers subdir - contains python helpers for load & flash etc.
5. firmware subdir - contains some modified BIOS files (relative to the original version)
6. software subdir - contains a separate build, load & flash logic for separate (RV32i) application code
   (the rest is of minor importance ...)

Quickstart

After installation of the relevant toolchains:

1. Open the project in VSC (or use your favourite IDE & maybe adjust some settings ;), adjust local paths if nec. ...
2. Connect your JTAG adapter as described in Wolfgang's documentation @ https://git.hacknology.de/wolfgang/colorlight
3. Run neopixelar.py with these options (you may omit the --doc option if there is no Sphinx installed): --build --load --revision=7.0 --uart-name=crossover --with-etherbone --ip-address=192.168.1.20 --csr-csv=build/csr.csv --doc to create & load the project to on-board SRAM via the USB/JTAG-Adapter (this takes it's time ...)
4. Connect a Neopixel LED chain to J4/Pin 1 (the logic supports 16 pins w/ 256 LEDs per chain, the demo features 3 pins w/ 27 LEDs each)
5. Press reset on the board, the LED chain should become illuminated
6. To program this base logic permanently, the board has to be improved, add a capacitor to stabilize the voltage for FPGA programming (see Wolfgang's documentation on https://git.hacknology.de/wolfgang/colorlight )
7. Now run the same sequence as mentioned above, replacing the --load option with the --flash option
8. This time it will take even longer ...
9. And hopefully complete without errors. If successful, the basic ROM s/w is now in place & operating. In case of errors try again - rule out EMI disturbances if nec.
10. Create the actual documentation for html via: 'sphinx-build -b html build/documentation build/documentation/html'
11. Use your favourite browser to access the 'npe' units documentation via 'file://your_projectpath/build/documentation build/documentation/html/index.html'

Individual (separate) applications

1. This time, open up a terminal & cd to the project local 'software' subdirectory
2. You can load an application to RAM bank 1:
   ./ramcreate.sh main illumination 1
3. To run the (now) RAM based application, type 'cd ..' within terminal
4. Connect the Litex-Terminal to the board via:
   wishbone-tool --ethernet-host 192.168.1.20 --server terminal --csr-csv build/csr.csv
5. Type 'ramboot' into terminal, the RAM based application should come up now
6. Press 's' (Speedup) to speed up the lights, 'w' (sloWdown) to slow them down
7. Press 'x' (eXit) to abort the application, you should see the LiteX prompt now
8. You can load an application to RAM bank 2:
   ./ramcreate.sh main illumination 2
9. Now, use 'ramboot' again! The system should swap to RAM bank #2 and boot the application right away
10. This is the testing loop, once your happy w/ your application, it needs to be flashed
11. !CAREFULL NOW! The application shouldn't contain any errors as it will be booted right after the BIOS automatically
12. Make sure, your JTAG adapter is in place!
13. Run:
    ./flashcreate.sh
14. This flashes the application permanently to the boot address, where it will be verified by the BIOS and started automatically (the good news: the 64kBytes of the sample application only take some 18 s ...)
15. You probably want to modify the application now ... (for development purposes, I recommend the quicker RAM bank
    loading - to get rid of an annoying flashed app, you may also use ./flashclearapp.sh ;)

Have fun!