Skip to content

Commit 1bc19e5

Browse files
vk2sebvk2seb
authored
docs: rewrite some sections, improve ToC (#98)
- Rearrange documentation layout to make it easier to navigate - Add new electrical design section - Rewrite some sections that could use the extra clarity
1 parent d285559 commit 1bc19e5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+549
-435
lines changed

‎doc/img/tiliqua-front-left.jpg

-47.6 KB
Binary file not shown.

‎doc/img/tiliqua-proto1-back.jpg

-35.3 KB
Binary file not shown.

‎doc/img/tiliqua-proto1-front.jpg

-40.2 KB
Binary file not shown.

‎doc/img/tiliqua-rear-left.jpg

-60.1 KB
Binary file not shown.

‎gateware/docs/_static/eurorack_pmod_bare_pcba_top.jpg

179 KB
Loading

‎gateware/docs/_static/soldiercrab.jpg

250 KB
Loading

‎gateware/docs/_static/tiliqua_disassembled.png

-722 KB
Binary file not shown.

‎gateware/docs/_static/tiliqua_disassembled_top.jpg

308 KB
Loading

‎gateware/docs/_static/tiliqua_motherboard_without_som.jpg

167 KB
Loading

‎gateware/docs/bootloader.rst

+65-58
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,29 @@
11
Bootloader
22
##########
33

4-
Interface
5-
---------
4+
User Interface
5+
--------------
66

77
The bootloader allows you to arbitrarily select from one of 8 bitstreams after the Tiliqua powers on, without needing to connect a computer. In short:
88

99
- When Tiliqua boots, you can select a bitstream with the encoder (either using the display output, or by reading the currently lit LED if no display is connected).
10-
- When you select a bitstream (press encoder), the FPGA reconfigures itself and enters the selected bitstream.
10+
- When you select a bitstream (press encoder), the bootloader bitstream:
11+
- Loads any required firmware to PSRAM and sets up any other settings requested in the bitstream manifest.
12+
- Commands the RP2040 over UART to issue a bitstream reconfiguration.
13+
- The RP2040 then commands the ECP5 (over JTAG) to reconfigure itself and enter the selected bitstream (loaded from the SPI flash local to the ECP5).
1114
- From any bitstream, you can always go back to the bootloader by holding the encoder for 3sec (this is built into the logic of every bitstream).
1215

13-
Setup and implementation
14-
------------------------
15-
16-
The bitstream selector consists of 2 key components that work together:
17-
18-
- The RP2040 firmware (`apfbug - fork of dirtyJTAG <https://github.com/apfaudio/apfbug>`_)
19-
- The `bootloader <https://github.com/apfaudio/tiliqua/tree/main/gateware/src/top/bootloader>`_ top-level bitstream.
20-
21-
First-time setup
22-
^^^^^^^^^^^^^^^^
23-
24-
1. Flash the RP2040. Use the latest pre-built binaries `found here <https://github.com/apfaudio/apfbug/releases>`_. To flash them, hold RP2040 BOOTSEL (golden button on the Tiliqua motherboard) before applying power, then copy the :code:`build/*.uf2` to the usb storage device and power cycle Tiliqua again. If you don't want to remove Tiliqua from your rack, you can also enter the RP2040 bootloader by opening a serial port at 1200 baud.
25-
26-
2. Build and flash the bootloader bitstream using the built-in flash tool (alternatively just download the latest bootloader archive from the CI artifacts):
27-
28-
.. code-block:: bash
29-
30-
# Flash bootloader to start of flash, build assuming XIP (execute directly from SPI flash, not PSRAM)
31-
# Be careful to replace `--hw r4` with your hardware revision!
32-
pdm bootloader build --hw r4 --fw-location=spiflash --resolution 1280x720p60
33-
pdm flash archive build/bootloader-r4/bootloader-*.tar.gz
34-
35-
3. Build and flash any other bitstreams you want to slots 0..7 (you can also download these archives from CI artifacts):
36-
37-
.. code-block:: bash
38-
39-
# assuming the archive has already been built / downloaded
40-
pdm flash archive build/xbeam-r4/xbeam-*.tar.gz --slot 2
41-
42-
2. Check what is currently flashed in each slot (by reading out the flash manifests):
43-
44-
.. code-block:: bash
45-
46-
pdm flash status
47-
48-
3. Before using the new bitstreams, disconnect the USB port and power cycle Tiliqua. (note: for the latest RP2040 firmware, this is not necessary and you can use them straight away).
49-
50-
.. warning::
51-
52-
Before ``apfbug`` beta2 firmware, the bootloader would NOT reboot correctly (just show a blank screen) if you have
53-
the :py:`dbg` USB port connected WITHOUT a tty open. You HAD to have the
54-
``/dev/ttyACM0`` open OR have the ``dbg`` USB port disconnected for it to work correctly.
55-
`Tracking issue (linked) <https://github.com/apfaudio/apfbug/issues/2>`_ (resolved in beta2 FW).
56-
57-
58-
4. Now when Tiliqua boots you will enter the bootloader. Use the encoder to select an image. Hold the encoder for >3sec in any image to go back to the bootloader.
59-
6016
Bitstream Archives and Flash Memory Layout
61-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17+
------------------------------------------
6218

63-
Each bitstream archive contains:
19+
Tiliqua user projects are packaged into *Bitstream Archives*, which are ``.tar.gz`` files that contain everything the bootloader needs to start a custom bitstream. Each bitstream archive contains:
6420

6521
- Bitstream file (top.bit)
6622
- Firmware binary (if applicable)
6723
- Any extra resources to be loaded into PSRAM (if applicable)
68-
- Manifest file describing the contents
24+
- Manifest file (human-readable ``.json``) describing the contents
6925

70-
The flash tool manages the following memory layout on the SoldierCrab's 128Mbit SPI flash:
26+
Tiliqua's ``pdm flash`` command manages the memory layout on the SoldierCrab's SPI flash, ensuring that the components of a bitstream archive end up in the correct place. A picture of how the SPI flash is organized:
7127

7228
.. code-block:: text
7329
@@ -129,13 +85,64 @@ If an image requires firmware loaded to PSRAM, the SPI flash source address (in
12985
That is, the value of ``spiflash_src`` is not preserved by the flash tool and instead depends on the slot number.
13086
This allows a bitstream that requires firmware to be loaded to PSRAM to be flashed to any slot, and the bootloader will load the firmware from the correct address.
13187

132-
Implementation details: ECP5
133-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88+
Flashing the RP2040 and bootloader bitstream
89+
--------------------------------------------
90+
91+
During normal use, it should not be necessary to flash the RP2040 or bootloader bitstream. However the instructions here may be useful for unbricking a device if you accidentally erased the bootloader, or want to update the bootloader on older hardware revisions. The bootloader is composed of 2 components that work together:
92+
93+
- The RP2040 firmware (`apfbug - fork of dirtyJTAG <https://github.com/apfaudio/apfbug>`_)
94+
- The `bootloader <https://github.com/apfaudio/tiliqua/tree/main/gateware/src/top/bootloader>`_ top-level bitstream.
95+
96+
Flashing Steps
97+
^^^^^^^^^^^^^^
98+
99+
1. Flash the RP2040. Use the latest pre-built binaries `found here <https://github.com/apfaudio/apfbug/releases>`_. To flash them, hold RP2040 BOOTSEL (golden button on the Tiliqua motherboard) before applying power, then copy the :code:`build/*.uf2` to the usb storage device and power cycle Tiliqua again. If you don't want to remove Tiliqua from your rack, you can also enter the RP2040 bootloader by opening a serial port at 1200 baud.
100+
101+
2. Build and flash the bootloader bitstream using the built-in flash tool (alternatively just download the latest bootloader archive from the CI artifacts):
102+
103+
.. code-block:: bash
104+
105+
# Flash bootloader to start of flash, build assuming XIP (execute directly from SPI flash, not PSRAM)
106+
# Be careful to replace `--hw r4` with your hardware revision!
107+
pdm bootloader build --hw r4 --fw-location=spiflash --resolution 1280x720p60
108+
pdm flash archive build/bootloader-r4/bootloader-*.tar.gz
109+
110+
3. Build and flash any other bitstreams you want to slots 0..7 (you can also download these archives from CI artifacts):
111+
112+
.. code-block:: bash
113+
114+
# assuming the archive has already been built / downloaded
115+
pdm flash archive build/xbeam-r4/xbeam-*.tar.gz --slot 2
116+
117+
2. Check what is currently flashed in each slot (by reading out the flash manifests):
118+
119+
.. code-block:: bash
120+
121+
pdm flash status
122+
123+
3. Before using the new bitstreams, disconnect the USB port and power cycle Tiliqua. (note: for the latest RP2040 firmware, this is not necessary and you can use them straight away).
124+
125+
.. warning::
126+
127+
Before ``apfbug`` beta2 firmware, the bootloader would NOT reboot correctly (just show a blank screen) if you have
128+
the :py:`dbg` USB port connected WITHOUT a tty open. You HAD to have the
129+
``/dev/ttyACM0`` open OR have the ``dbg`` USB port disconnected for it to work correctly.
130+
`Tracking issue (linked) <https://github.com/apfaudio/apfbug/issues/2>`_ (resolved in beta2 FW).
131+
132+
133+
4. Now when Tiliqua boots you will enter the bootloader. Use the encoder to select an image. Hold the encoder for >3sec in any image to go back to the bootloader.
134+
135+
136+
Technical Details
137+
-----------------
138+
139+
Bootloader bitstream: ECP5
140+
^^^^^^^^^^^^^^^^^^^^^^^^^^
134141

135142
The ECP5 :code:`bootloader` bitstream copies firmware from SPI flash to PSRAM before jumping to user bitstreams by asking the RP2040 to execute a stub bitstream replay (load a special bitstream to SRAM that jumps to the new bitstream). The request is issued over UART from the ECP5 to the RP2040, so it is visible if you have the ``/dev/ttyACMX`` open. User bitstreams are responsible for asserting PROGRAMN when the encoder is held to reconfigure back to the bootloader.
136143

137-
Implementation details: RP2040
138-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
144+
`apfbug` debugger firmware: RP2040
145+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
139146

140147
:code:`apfbug` firmware includes the same features as :code:`pico-dirtyjtag` (USB-JTAG and USB-UART bridge), with some additions:
141148

‎gateware/docs/calibration.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -75,4 +75,4 @@ In short, the process is as follows:
7575

7676
.. note::
7777

78-
During calibration, you may notice the DC offsets moving around ~10mV depending on whether the LEDs are on or off. Unfortunately there is no simple workaround for this as it seems the CODEC DC offsets depend on the CODEC supply voltage, despite us using a dedicated voltage reference. You may also see some higher offsets at high negative voltages. This may be an artifact of us using the CODEC in an unsupported DC-coupled mode, we're not entirely sure yet. In any case, it's best to do the calibration assuming the LEDs are ON, as that is the state they will be in most of the time Tiliqua is being used.
78+
During calibration, you may notice the DC offsets moving around ~10mV depending on whether the LEDs are on or off. Unfortunately there is no simple workaround for this as it seems the CODEC DC offsets depend on the CODEC supply voltage, despite us using a dedicated voltage reference. You may also see some higher offsets at high negative voltages. This is likely an artifact of us using the CODEC in an unsupported DC-coupled mode. In any case, it's best to do the calibration assuming the LEDs are ON, as that is the state they will be in most of the time Tiliqua is being used. In the future, it should be possible to even calibrate out the effect of supply voltage changes to the CODEC, as the Tiliqua knows at all times how much power the audio PCBA should be consuming.

‎gateware/docs/conf.py

+3-3
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
from importlib.metadata import version as package_version
66

77

8-
project = "Tiliqua Project"
8+
project = "Tiliqua"
99
copyright = time.strftime("2024—%Y, S. Holzapfel and Tiliqua contributors")
1010

1111
extensions = [
@@ -21,7 +21,8 @@
2121
with open(".gitignore") as f:
2222
exclude_patterns = [line.strip() for line in f.readlines()]
2323

24-
root_doc = "cover"
24+
html_use_modindex = False
25+
html_use_index = False
2526

2627
intersphinx_mapping = {
2728
"python": ("https://docs.python.org/3", None),
@@ -53,7 +54,6 @@
5354

5455
html_theme = "sphinx_rtd_theme"
5556
html_static_path = ["_static"]
56-
html_css_files = ["custom.css"]
5757
html_logo = "_static/logo.jpg"
5858

5959
rst_prolog = """

‎gateware/docs/hardware.rst ‎gateware/docs/connections.rst

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
Connecting Hardware
2-
###################
1+
Connections
2+
###########
33

44
Connections: Front
55
------------------

‎gateware/docs/cover.rst

-10
This file was deleted.

‎gateware/docs/dsp.rst

-84
This file was deleted.

‎gateware/docs/dsp/delay_lines.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Delay Lines
2+
-----------
3+
4+
.. autoclass:: tiliqua.delay_line.DelayLine
5+
.. autoclass:: tiliqua.delay_line.DelayLineTap
6+

‎gateware/docs/dsp/effects.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Effects
2+
-------
3+
4+
.. autoclass:: tiliqua.dsp.WaveShaper
5+
.. autoclass:: tiliqua.dsp.PitchShift

‎gateware/docs/dsp/filters.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Filters
2+
-------
3+
4+
.. autoclass:: tiliqua.dsp.SVF
5+
.. autoclass:: tiliqua.dsp.FIR
6+
.. autoclass:: tiliqua.dsp.Boxcar

‎gateware/docs/dsp/index.rst

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
DSP Library
2+
###########
3+
4+
Philosophy
5+
----------
6+
7+
TODO short overview of the DSP library philosophy.
8+
9+
TODO link to Amaranth documentation on streams.
10+
11+
.. image:: /_static/mydsp.png
12+
:width: 800
13+
14+
DSP Components
15+
--------------
16+
17+
.. toctree::
18+
:maxdepth: 2
19+
20+
delay_lines
21+
filters
22+
oscillators
23+
effects
24+
vca
25+
mix
26+
resample
27+
oneshot
28+
stream
29+
misc

‎gateware/docs/dsp/misc.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Miscellaneous utilities
2+
-----------------------
3+
4+
.. autofunction:: tiliqua.dsp.named_submodules

‎gateware/docs/dsp/mix.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Mixing
2+
------
3+
4+
.. autoclass:: tiliqua.dsp.MatrixMix

‎gateware/docs/dsp/oneshot.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
One-shot
2+
--------
3+
4+
.. autoclass:: tiliqua.dsp.Trigger
5+
.. autoclass:: tiliqua.dsp.Ramp

‎gateware/docs/dsp/oscillators.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Oscillators
2+
-----------
3+
4+
.. autoclass:: tiliqua.dsp.SawNCO

‎gateware/docs/dsp/resample.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Resampling
2+
----------
3+
4+
.. autoclass:: tiliqua.dsp.Resample

‎gateware/docs/dsp/stream.rst

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Stream utilities
2+
----------------
3+
4+
Splitting / merging streams
5+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
6+
7+
.. autoclass:: tiliqua.dsp.Split
8+
.. autoclass:: tiliqua.dsp.Merge
9+
10+
Connecting and remapping streams
11+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
12+
.. autofunction:: tiliqua.dsp.connect_remap
13+
.. autofunction:: tiliqua.dsp.channel_remap
14+
15+
Connecting streams in feedback loops
16+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17+
18+
.. autoclass:: tiliqua.dsp.KickFeedback
19+
.. autofunction:: tiliqua.dsp.connect_feedback_kick

‎gateware/docs/dsp/vca.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
VCAs
2+
----
3+
4+
.. autoclass:: tiliqua.dsp.VCA
5+
.. autoclass:: tiliqua.dsp.GainVCA

0 commit comments

Comments
 (0)