When we bought a puppy about a year ago we did not have the facilities that a typical dog owner should have home. Particularly useful is a dog kennel so you can for instance hang up your wet laundry in peace. Also you create a refuge for the dog. A dog kennel is often recognized as a safe space for your furry friend.

As always there are many roads leading to Rome. I would like to share how we have done it. Buying wasn't really an option- way too easy! Moreover, one is under the impression to be able to save money on the D.I.Y. side of things.

1. We dug about 60 cm to 1 m into the ground. The ditch was about 30 cm to 60 cm wide.
2. Then we plunged concrete blocks into the ground. They should rest upon a bed of sand or gravel. We used gravel and some old concrete plates making it easier to level the whole construction later. In this step it is handy to use a cord in order to get 90° angles and straight lines.
3. In the third step we connected the concrete blocks w/ long planks (120 mm x 45 mm) creating the frame for the kennel just a few centimeters above the ground. Important to mention is that our concrete blocks feature a post anchor optimized for 45 mm. Before fastening the planks to the concrete blocks with screws it is important that the frame is leveled. It can be necessary to add or remove material under the concrete blocks if you do not have adjustable post anchors. In our case we tried to hoist or lower the concrete blocks and only for the last 1 cm to 2 cm we shifted the planks inside the post anchors.
4. Next up you raise the vertical posts. Our construction utilized 120 mm x 28 mm planks. One could argue that these posts are maybe a bit to puny. The solution is to double them if deemed necessary i a certain place. Anchorage w/ the lower frame was achieved by a L shaped cutout and long screws from the inside of the kennel.
5. For the sake of stability we created a second frame connecting all the tops of the posts. 120 mm x 28 mm was used again because it was cheap. When the planks were to short they would have been connected w/ L shaped cutouts, wood glue and screws.
6. In this step we designed a simple door and connected the kennel to the deck. Around the door we used some brackets and multiple planks on top of each other to get a sturdier construction.
7. Painting. Some elements got colored in "Falu rödfärg" and others white. It is worth mentioning that all wood used in this project is pressure treated since the construction is exposed to a harsh and wet climate.
8. Installing fence. We bought a 1.8 m chain wire fence for above the ground and laid a 0.5 m fence in the ground to make escape through dug tunnels impossible.

When it is cold and dark in winter some people like to gather, light a fire and denaturate junks of proteins together w/ the help of its heat once it burned down a bit. To do so a sucture is necessary, that gives room for, but also can contain the cheering flames, on the one side. On the other side the setup needs to allow to hold a grill grate once it is time to broil that tasty spareribs. Another important requirement is, that the arrangement can hold a beer, because, it is reasonable to become a little thirsty when cooking over an open fire, that brings the sweat to your face. Of course, it is also convenient to be able to place an empty bord, barbecue cutlery or spices directly next to where the meat is being cooked. Everybody can buy a grill. Everybody can grill with gas. Not everybody can use a scrap barrel and give it a new purpose. I was really trying to get my head arround this complex, but important problem for some time and this is the design I came up with:

Two Xes hold together by three threaded rods make up for the basic structure. The legs are fitted with pads welded onto them so that the grill stands propely and does for instance not get tilted by one leg sinking into the snow. Also it features a stop to be able to get the right angle with each X. With an angle grinder a barrel of brake cleaner was cut in half, that is where wood and/or charcoal can be burned. On one side two arms are attached in a way, that wodden planks could be mounted to form a small surface.

Lesson learned: The grate could be a bit bigger. It is dimensioned to be only slightly bigger than the barrel. If it ended up being just a little misaligned in the heat of the battle, it could easily happen to fall down into the embers.

To be honest, I borrowed a bigger junk of the headline from Jenny List, an active Hackaday author. A recent article of hers^[1] inspired me to write something about the whole environmental sustainability is not affordable opinion, that she started off to plead for with cars in her article.

People who know me would describe me as a rather conservative consumer always being very careful and frugal about all sorts of investments. Just like almost every tech guy / girl, I have also been interested in Electric Vehicles (EVs) for a long time. When I was an undegraduate in 2013, as students, we had the possibility offered by the Deutsche Bahn to rent a Renault Zoe ZE for 1 € per 15 minutes. I think this programme of the DB is called Flinkster nowadays. The campus was located on the outskirts of the city, but we had one of those car sharing places on it. Four people driving to the city during lunchbreak for an hour to eat a pizza was an offer coming at an attractive price. Ever since, I wanted to own a car with an electric drivetrain. The technology is simply superior due to many aspects, but the economical one, right?

In many cases, driving an EV is quite certainly "a lifestyle choice enabling the well heeled to pat themselves on the back for their chequebook environmentalism" as Ms. List writes in her article. I sure do agree on that one. However, her message about electric cars is wrong from my point of view. It is irrational, as far as I can see, not really fact-based, which is not how a technologist should approach a topic. She writes "I can just about find one that’s maybe a decade old, but when its range is less than I can easily cycle without getting tired it becomes little more than a very expensive automotive project in terms of its use to me". It would hardly be an exaggeration to say, that cycling a daily commute of 50 km is too much for the average Jill or Joe. A Nissan Leaf with only about 50 % State of Health (SoH) left can easily achieve this task in winter. And this is really only happening after many kilometers of driving, mine has arround 83 % SoH left w/ 8 years on its back. Personally, I do believe Ms. List neither has an integral view on the expenses of a car during the time it is owned by someone in general nor did she look very well into the second-hand market in Great Britain, which is known to be the second biggest sales market for Nissan Leafs in Europe^[2].

I was wondering about this questions whether an EV is really a way to safe money or not and I came to the conclusion: it depends! If you buy a brand new Polestar 2 when you would rather buy a second-hand, few years old BMW X1 w/ a diesel engine, sure the Scandinavian glamour boy will cost you maybe 70 % less per kilometer, but you will have a long time to catch up with the initial extra costs. On the contrary, if you for instance get a second car w/ an electric drivetrain for you and your family and try to avoid kilometers w/ your combustion car, you may find, that your investment will be amortized in a short time. However, it is important to throw in the determining factors.

I worked on a calculation model and casted it into a small script, that I would like to introduce here. The result for my personal situation is, that by avoiding to put kilometers on my diesel off-road vehicle by using my Leaf instead, I will have its purchase price completely amortized after ca. 2 1/2 years or ca. 50 000 km, which sounds fine to me.

As always in life, this "financial strategy" comes at a certain risk. If the battery degrades by a too high percentage during this 50 000 km, the amortization would be postponed, because I could not take the car for longer rides. But empirical evidence^[3] is showing, that the degradation happens at an almost constant rate. Most likely in my climate (central Europe) the 24 kWh 2013 model Leaf battery is subject to calendaric aging only if it is charged / discharged avoiding excessive heat.

Source^[4]: Myall, D.; Ivanov, D.; Larason, W.; Nixon, M.; Moller, H. Accelerated Reported Battery Capacity Loss in 30 kWh Variants of the Nissan Leaf. Preprints 2018, 2018030122 (doi: 10.20944/preprints201803.0122.v1).

17 % degradation in 8 years is being equal to approx. 2 1/8 % a year. Extrapolating this number linearly, I will end up with less than 5 1/2 % degradation when the car is amortized. This is a simplification, because the authors of the paper found out, that there is a slight increase of the aging rate of the 24 kWh battery.

Perhaps, this estimation approach is completely wrong, since the battery starts degarding much faster when its approaching its end of life. I could not find much reliable data on the internet about batteries as old as mine. But even assuming a worst-case of another 17 % degaradation, would leave me with 66 % SoH. This would mean that I could still drive for about 80 km until the battery is empty. I commute less than that and the Swiss🇨🇭 average definitely commutes less than that as well, with ca. 15 km a day (one-way)^[5].

To warp up, I am convinced, that we reached the point in time where you can strike marvelous deals on the second-hand EV market. Depending on your personal circumstances, e.g.

• Can you charge for free at a lot of places (employer, supermarket etc.)?
• Are there tax or insurance bonuses in your state or area?
• Are the gas prices high and the electricity prices low?
• Can you divert excessive energy from your homestead solar system into the car's battery?

chances are higher or lower, that an EV is the more economic choice. Electromobility is definitely not only a rich man's game anymore, but we mortals can play it as well.

For my script^[6] communicating your personal situation to the computer happens by creating a JSON file. It is easiest to copy the one in the repository and adapt the values of the objects. I think they should be pretty self-explanatory. Here is the example:

{
    "currency": "CHF",	
    "kwh_price_home": 0.2,
    "kwh_price_commercial": 0.5,
    "juice_litre_price": 1.75,
    "kilometers_per_year": 20000.0,
    "ecar": {
	"label": "Nissan Leaf 2013",
        "price": 7600,
        "taxes": 0,
        "insurance": 354,
        "kwh_per_kilometer": 0.16,
        "maintenance": 100,
        "charging_behaviour": {
            "percent_free_charges": 90,
            "percent_home_charges": 5,
            "percent_commercial_charges": 5
         }
    },
    "ccar": {
        "label": "Suzuki Grand Vitara 2008",
        "price": 7000,
        "taxes": 350,
        "insurance": 362,
        "litres_per_kilometer": 0.08,
        "maintenance": 1000
    }
}

Our summer cottage entirely reflects the farmer lifestyle of most of our ancestors in Europe. It was a simple life, but most likely also a peaceful one. The husband was typically a lumberjack 👨🪓🌳 in the winter and the wife would take care of the farm during that time besides her many other duties in the household. When the temperatures rose they would both be busy haying for the cattle and farming crops and berries. This property was established in 1937 and a dream must have come true for our predecessors who built this house and lived here.

A Swedish politician named Per Albin introduced a cheap mortage in the 1930s the state would issue for the population on the countryside, that made it possible for many people of the working class to move into their own homestead ^[1] and ^[2].

However, there was no running water, electricity or a water closet. According to an old receipt, that was collected and retained carefully by the previous owners along with other important documents, the first time electricity was draged into the house was in the 1970s, but when we took over the house we only found leftovers like cabling and lightbulb lamps in the barn. Most likely the power lines were removed due to the annual basic costs. The most romantic foundation for a clean off-grid energy production from my point of view.

So I started reading into the subject. I must admit, that although I have a technical background, this is not as easy as repainting the house with Rödfärg, the typical Swedish red house paint^[3]. The system I came up with is fully customized to the market situation, as well as the unique energy consumption and storage requirements of an off-grid facility. I want to share my design mainly because it was a bit difficult to find something comparable on the WWW, since one needs to adhere to the local regulation, which, however, seems pretty much comparable between different countries at least in Europe.

Our off-grid solar design

The system can be simplified to something like this:

Some quick facts about the system:

• Maximum peak power output of the generator: 6.56 kW
• Four strings à four panels w/ 410 W
• Two string à four batteries 120 Ah @ 12V which is about 11.5 kWh storage capacity
• Maximum charge current of 60 A = 2.88 kW.
• Completly off-grid, no (integrated) backup generator so far
• Electric energy abundance between March and September
• 3 kW inverter
• 48 V / 24 V conversion incl. fuse box for LED lights and other appliances that can be DC driven

The solar generator is the part that actually converts sunlight into an electric current through the photovoltaic effect ^[4]. Depending on the type of solar cells and the coupling scheme the output voltage varies, but generally speaking, the output voltage here can be rather dangerous, because it is a high DC voltage, no zero crossing. The tracker / charger, comercially available under the term Maximum Power Point Tracker (MPPT), presents a certain impedance to the generator and converts it to a necessary impedance presented to the batteries. From hereon we are in the 48 V domain, which is uncritical to us human beings.

The illustration below can help to explain what a MPPT is doing: The load is adapted so, that the current and voltage end up in a knee point, where the maximum power under the given environmental circumstances (light, shadow and temperature) is obtained. In the illustration a line goes through the maximum power points. Read more on the subject and find the image source under ^[5].

All energy produced ends up being "consumed" instantly through DC devices (ommited in the diagram above), AC devices behind the inverter or stored in the batteries. A 48 V system voltage corresponding to four 12 V batteries in series is chosen, so that the wire diameter does not get too big. For connecting the 3 kW inverter to the 48 V bus bars 50 mm² cables are employed. With insulation this equals a diameter of arround 12 mm. These kind of thick cables are already difficult to bend, so having an even lower voltage e.g. 24 V, corresponding to two lead-acid batteries in series, was not an option for me since we wanted the same convenience that you have in a modern house nowaydays. The premise was to draw loooots of power e.g. with big tools like saws or angle grinders.

Does only solar mean I have to sit in the dark from time to time?

According to the Swedish ministry for statistics Statistiska centralbyrån (SCB) a Swedish household consumes on average 2000 kWh / anno to 5000 kWh / anno ^[6]. We assume that with our rather conservative lifestyle e.g. heating with wood, avoiding long showers etc. we would have an energy need of arround 3000 kWh / anno = 8.2 kWH / day in order to find out when we would not have enough energy available. According to the Victron Energy simulation tool ^[7] without additional measures we would sooner or later run out of electric energy when taking a vacation between October and February (cf. diagram below). Not a problem for a summer house is it?

Lead-acid vs. lithium-ion battery

In my opinion, just like driving an electric car (yes I am a big fan!) this is rather a question of economy than a question of technology. The aforementioned design uses flooded lead-acid batteries, that include some smart engineering to make them more durable in terms of the number of cycles and Depth of Discharge (DoD), not comparable to the lead-acid batteries in your EV or combustion car. A technological reason to go for lead-acid batteries is certainly the cold climate in Norrland. While the Lithium battery chemistry fails you w/ temperatures below 0 °C ^[8], the lead-acid battery still does not freeze below -65 °C ^[9]. However, the main reason is, that quality batteries cost so much less most likely due to the time the technology had to evelove. Even the cheapest Chinese Pylontech US2000C ^[10] costs arround SEK 3250 / kWh while the technology I am using is arround SEK 700 / kWH and we talke about German quality ware. Of course, Lithium-ion batteries last longer in terms of the number of cycles, which is for our use-case not going to be high in a summer cottage.

The entire design is documented here. I will try to keep it up-to-date including the modifications that will likely come in the future.

Recently, I was traveling with the train again and it so happened, that I was coming to Germany🇩🇪. It is not a secret, that things the train operators in neighbouring countries master effortlessly, seem to set a difficult challenge for the Deutsche Bahn (DB). To feed this statement with numbers: around 20 % of all trains in Germany were late in 2020 and that does not include the trains, that were cancelled for good or trains, that were less than 6 minutes late ^[1].

So it comes as no surprise, that I had problems connecting my Linux distribution workstation to the DB Wifi available on all ICEs^[2].

$ cat /etc/os-release 
PRETTY_NAME="Debian GNU/Linux 10 (buster)"
NAME="Debian GNU/Linux"
VERSION_ID="10"
VERSION="10 (buster)"
VERSION_CODENAME=buster
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"

And ofcourse I was not the first person in 2021 that complained, but apparently the DB did not put any measures in place. One problem is the poorely chosen IP addresses range, as people report ^[3] or ^[4].

The best (quickest) solution I came up with was to connect my Sailfish OS phone🐟 to the Wifi and use it as a Wifi adapter. Since Sailfish OS version 4.0.1.48 (Koli) does up to the best of my knowledge not support Wifi to USB tethering, I had to put in some work.

The trick was to setup a SOCKS5🧦 tunnel to the phone using USB as a physical layer. I am gonna start in laying out how I setup the connnection.

You fire up your terminal and type

$ ssh -D 5100 -C -N -q nemo@192.168.2.15

This forwards all traffic directed to 127.0.0.1:5100 to the phone, which has internet access over Wifi. Data can ofcourse also come back through that port. For more details about SOCKS and the command parameters checkout ^[5]. Mattias Geniar explains this much better than I ever could.

Sidenote:

SOCKS is definitely good for many things especially if you suspect a network, where your traffic is routed through, to have malicious susbscribers, trying to spy on you.

Next you need to tell your system or individual programs to route the data through the tunnel.

Firefox:

Telegram:

Thunderbird:

Optimally, your phone is connected to a VPN or your server using SOCKS as well, since you cannot really trust a public Wifi like that. Enjoy!

Introduction

When I was writing my master thesis^[1] I wanted the figures to look professional, meaning I wanted at least the same font in the figure as used all over my document. However, TikZ^[2] was not an option, because I wanted to focus on the actual programming (and signal processing) tasks and not too much on my love for beautiful documents in the little time I was given. I searched the world wide web and I had a Morpheus moment when I came across the inkscape^[3] --export-latex option.

Sounds pretty good, right? The suggested workflow with inkscape is a follows.

Create a SVG w/ Python

Let's get our hands dirty right away. As a first step an image needs to be created. Theoretically, it does not matter how the SVG is produced. I tried Python and draw.io.

The image decorating this post is a screenshot of a LaTeX compiled PDF. To give an example, I am going to show how to make those two plots leveraging Python in conjuction with matplotlib^[4]. Here comes an excerpt of the code, which created those two waveforms.

from matplotlib import pyplot as plt
import numpy as np
from matplotlib.ticker import EngFormatter

# Settings
plt.rcParams['font.size'] = 12
plt.rcParams['svg.fonttype'] = 'none'

# Master thesis colors
color0 = '#00285e'

# Sexy formatter engineering style
formatter0 = EngFormatter(unit='')
formatter1 = EngFormatter(unit='s')

w = float(1)/15e3
carriers = 12
x = np.linspace(-15e3*(carriers+2),15e3*(carriers+2),1000)

# Single carrier
b = np.sinc(x*w)
plt.plot(x,b,label="\$\\frac{sin(f)}{f}\$", linewidth=3, color=color0)

# Plot formatting
axes = plt.gca()
axes.xaxis.set_major_formatter(formatter0)
axes.set_xlabel("\$f/\SI{}{\Hz}\$")
for side in ['right','top','left']:
  axes.spines[side].set_visible(False)
axes.xaxis.labelpad = 15
axes.yaxis.labelpad = 15
plt.title("Single \gls{NB-IoT} Sub-Carrier")
plt.yticks([])
plt.savefig("ofdm_nbiot_sinc.svg", format="svg", transparent=True)
plt.clf()

# Pulse shape
t = np.linspace(-(1/15e3), 1/15e3, 1000)
boxcar = [0]*(len(t)/4) + [1]*(len(t)/2) + [0]*(len(t)/4)
plt.plot(t,boxcar,label="\$s(t)\$", linewidth=3, color=color0)

# Plot formatting
axes = plt.gca()
axes.set_xlabel("\$t/\SI{}{\second}\$")
axes.xaxis.set_major_formatter(formatter0)
for side in ['right','top','left']:
  axes.spines[side].set_visible(False)
axes.xaxis.labelpad = 15
axes.yaxis.labelpad = 15
plt.title("\gls{NB-IoT} Pulse-Shape")
plt.yticks([])
plt.savefig("ofdm_nbiot_boxcar.svg", format="svg", transparent=True)
plt.clf()

Now there are two SVGs in that directory, which can be further processed.

Converting the SVG to LaTeX

The second step is pretty straight forward. Once you have a .svg file. You can feed it into inkscape and their great plugin will take care of (almost) all the rest.

inkscape -D --export-latex --export-filename=./figs/ofdm_nbiot_boxcar.pdf ./figs/ofdm_nbiot_boxcar.svg

As one can see, in that case all figures are stored in a directory called figs. This might concern you, since you found out, that the produced .pdf_tex file references to ofdm_nbiot_boxcar.pdf directly. I fixed this issue by calling rpl, a neat program to replace strings in files.

rpl -q ofdm_nbiot_boxcar.pdf ./figs/ofdm_nbiot_boxcar.pdf ./figs/ofdm_nbiot_boxcar.pdf_tex

Fixed it! Basically, you could also open the .pdf_tex output file in a standard editor and just find & replace every occurance (if you have nothing else to do).

Interfacing w/ LaTeX

All you need to do next is to include the following lines into your LaTeX document.

\begin{figure}[htbp]
  \begin{subfigure}{0.49\columnwidth}
    \centering
    \scriptsize
    \def\svgwidth{\columnwidth}
    \input{./figs/ofdm_nbiot_boxcar.pdf_tex}
    \caption{}
    \label{fig:ofdm_nbiot_boxcar}
  \end{subfigure}
  \begin{subfigure}{0.49\columnwidth}
    \centering
    \scriptsize
    \def\svgwidth{\columnwidth}
    \input{./figs/ofdm_nbiot_sinc.pdf_tex}
    \caption{}
    \label{fig:ofdm_nbiot_sinc}
  \end{subfigure}
  \caption{Pulse shape of a \gls{NB-IoT} signal (a) and spectrum of one subcarrier (b).}
  \label{fig:ofdm_shape_spectrum_1}
\end{figure}

In the example above each figure is scaled to the \columnwidth by calling \def\svgwidth{\columnwidth}. Moreover, the font size is set to \scriptsize (read all about it in ^[5]). These parameters can be modified to suit your personal needs. Above all there is a small document describing the inkscape plugin ^[6].

Adding convenience

Personally, I typically set up a small build system with Make ^[7] if I work on a larger LaTeX document for a longer time. However, there are many folks out there who appreciate the convenience, that overleaf.com poses, which I fully understand. Sometimes you also just work on some small LaTeX document and do not want to set up a complicated directory structure including a custom build system. I do this as well. For this reason, I wrote the prehaps ugliest webapp in the world. This webapp does all the aforementioned steps (after you have created a SVG) for you.

Here is the source code and you can access this app under v2l.stiefel.tech/converter.php.

How to use the app?

1. Enter the name of the directory where you have stored your images e.g. figures.
2. Upload the SVG file.
3. Press Convert.
4. Download the resulting files.

If you have any suggestions what to change about this app, please let me know in the comments below.

VHDL supports clean modular structures enabling to easily reuse your code. In this post I will explain how to create a VHDL library for simulation utilizing GHDL ^[1] in combination with GTKWave ^[2] and optionally blend these with the advantages of a git submodule ^[3].

Both GHDL and GTKWave are free (as in freedom) software bundles licenced under the GPLv2 ^[4]. git is licences under ... well you certainly already know.

Packages and libraries in VHDL

Writing your first line of VHDL code implies accessing a library (provided, that you write your code in a linear fashion). Every digital designer working with VHDL is familiar with statements like the following.

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

ieee is the library shipped with the VHDL compiler and simulator, which is GHDL in our case. std_logic_1164 and numeric_std are so called packages. std_logic_1164 provides us with types like std_logic and corresponding values like '1' or 'U'. Whereas numeric_std deals with numerical computation involving e.g. the type unsigned.

Let's dive into it and take a look at the std_logic_1164 package. Depending on the VHDL standard (VHDL is maintained by the IEEE ^[5]) a different package is used. One implementation can be found in the GHDL repository ^[1:1] under libraries/ieee/stdlogic1164.vhdl. In this file we find a lot of interesting things to look at. For instance, we find the declarations for the edge detectors, which are typically employed when sequential logic needs to be created.

-------------------------------------------------------------------
-- edge detection
-------------------------------------------------------------------
function rising_edge  (signal s : STD_ULOGIC) return BOOLEAN;
function falling_edge (signal s : STD_ULOGIC) return BOOLEAN;

Packages in VHDL consist of a declaration and a body. Those two parts can be in one or two seperate files (per package). To give an example, in GHDL for the package std_logic_1164 there is the file stdlogic1164.vhdl

package std_logic_1164 is
-- Declarations
end std_logic_1164;

and the file std_logic_1164-body.vhdl in the very same directory:

package body std_logic_1164 is
-- Implementations
end std_logic_1164;

The edge detectors for instance are implemented like this (in this particular VHDL version).

-------------------------------------------------------------------
-- edge detection
-------------------------------------------------------------------
function rising_edge (signal s : STD_ULOGIC) return BOOLEAN is
begin
return (s'event and (To_X01(s) = '1') and
        (To_X01(s'last_value) = '0'));
end rising_edge;

function falling_edge (signal s : STD_ULOGIC) return BOOLEAN is
begin
return (s'event and (To_X01(s) = '0') and
        (To_X01(s'last_value) = '1'));
end falling_edge;

If you want to improve on the structure of your VHDL code your own library (or even libraries) are the best bet you have. The first step is to create a package and define e.g. components inside it. I am not going into the details of VHDL packages too much because others have done that very well before me ^[6]. Do your research and then you can take the next step.

Adding a library to your project

If this was a cookbook the following section would present a recipe on how to cook the dish I promised in the introduction. First you should have a recent version of GHDL, GTKWave and git installed. As a reference I share my setup with you here.

$ gtkwave --version
GTKWave Analyzer v3.3.98 (w)1999-2019 BSI
...

$ ghdl --version
GHDL 1.0-dev (v0.37.0-819-g9828b513) [Dunoon edition]
...

$ git --version 
git version 2.20.1

If you have not already, then now it is time to fire up your favorite shell.

So, let's assume you want to create some design, that takes my UART implementation as a building block. Assuming, that you use git already to track your design files, we start with creating a submodule.

git submodule add https://git.stiefel.tech/m3x1m0m/max_uart_vhdl.git

Submodules ^[7] are a great way to improve the live of designer who dislikes reinventing the wheel. In a VHDL file, let's call it top.vhd in this example we want to instatiate a UART transmitter and interface with the rest of our design. In the section above we saw, that we need to tell the compiler about the library and the packages within, which kind of makes the creation of a package necessary in the first place. I made a very simple package uart.vhd. It is part of the submodule, that we just added.

-- uart.vhd
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

package uart_pkg is
  component uart_tx is
    port(
          i_clk_baudrate  : in  std_logic;
          i_reset_n       : in  std_logic;
          i_tx_send       : in  std_logic;
          i_tx_data_vec   : in  std_logic_vector(7 downto 0);
          o_tx_pin        : out std_logic;
          o_tx_sent       : out std_logic
        );
  end component;
end package;

Because of the package we now can simply add the UART transmitter to our design adding the following lines of code to the aforementioned top.vhd.

library max_uart;
use max_uart.uart_pkg.all;
-- Alternatively we could write ...
-- use max_uart.uart_pkg.uart_tx;

Now we reached a turning point. The remaining tasks are tool specific and I will show, which commands have to be issued to get it done with GHDL and GTKWave.

In Lattice Diamond adding libraries is also a piece of cake. I might share how I have done it in a later blog post.

Libraries in GHDL

The directory structure looks like this for my specific case.

$ tree .
.
├── LICENSE
├── pixel_line_cnt.gtkw
├── pixel_line_cnt_tb.vhd
├── pixel_line_cnt.vcd
├── pixel_line_cnt.vhd
├── README.md
├── top.gtkw
├── top_tb.vhd
├── top.vcd
├── top.vhd
└── uart_vhdl
    ├── clock_divider_tb.vhd
    ├── clock_divider.vhd
    ├── LICENSE
    ├── README.md
    ├── string_sender.gtkw
    ├── string_sender_tb.vhd
    ├── string_sender.vhd
    ├── top_ecp5_eval.lpf
    ├── top.gtkw
    ├── top_tb.vhd
    ├── top.vhd
    ├── uart_tx.gtkw
    ├── uart_tx.pcf
    ├── uart_tx_tb.vhd
    ├── uart_tx.vhd
    └── uart.vhd

First, we tell GHDL about the necessary design files in the submodule. To not polute the UART directory with output files, it makes sense to create a work directory. The same applies for the main project.

$ mkdir uart_vhdl/work && mkdir work

There are more advanced usage options of GHDL, but for now we analyze individual files, check if we have everything and then execute our simulation.

In my particular case I need the following files to be known be GHDL.

$ ghdl -a --workdir=uart_vhdl/work --work=max_uart uart_vhdl/uart.vhd
$ ghdl -a --workdir=uart_vhdl/work --work=max_uart uart_vhdl/uart_tx.vhd
$ ghdl -a --workdir=uart_vhdl/work --work=max_uart uart_vhdl/clock_divider.vhd

$ ghdl -a --workdir=work --work=work pixel_line_cnt.vhd
$ ghdl -a -Puart_vhdl/work --workdir=work --work=work top.vhd

If the top design where the library is included can be analyzed w/o GHDL puking, you have done everything right.

Basically, two libraries are created: The default work library and our own library, which is called max_uart in that case.

With the --dir option we can check whether it GHDL understood what we want from it.

$ ghdl --dir --workdir=uart_vhdl/work --work=max_uart
# Library max_uart
# Directory: uart_vhdl/work/
package uart_pkg
entity clock_divider
architecture clock_divider_rtl of clock_divider
entity uart_tx
architecture uart_tx_rtl of uart_tx

Nice! The same we can do for our default work library to double-check if GHDL is set up straight. I can now analyze and execute the testbench of my top design, the entity top_tb.

$ ghdl -a -Puart_vhdl/work --workdir=work --work=work top_tb.vhd
$ ghdl -r -Puart_vhdl/work --workdir=work --work=work top_tb --vcd=top.vcd

--vcd creates a file, that we can feed into our wave viewer. I noticed, that GHDL can be quite bitchy with the order of CLI arguments. I guess there is no argparse implementation for Ada- haha. (GHDL is written in Ada.)

For further information on GHDL usage you should take a look at the GHDL manual ^[8].

As a last step we ask GTKWave to display the freshly generated waveforms.

$ gtkwave top.vcd top.gtkw

Personally, I like to have my sessions settings stored in a .gtk file as you can see above.

I hope this article helped you to get your head around how to construct a clean design structure for your VHDL project, that leverages GHDL, a tremendous tool.