Peace Memorial Park, Hiroshima

DS3231 RTC on Raspberry with Fedora

A minor downside of the Raspberry Pi is that it is not equipped with a battery backed-up real-time clock. After every reboot, the system time is messed up and needs to be corrected by NTP, which in turn requires a network connection.

Luckily, there are readily assembled RTC modules available. They base on the DS3231 real time clock chip. A tiny battery is keeping the time when the Raspberry is disconnected from power. You can find those modules for less than two Euros a piece at marketplaces like Amazon, eBay, or Alibaba. The module is just plugged onto the pin header of the RasPi.

It is quite easy to use the RTC on Raspbian. On Fedora for Raspberry Pi, the installation was a little more tricky though.

In a first step, the RTC must be added as a new I²C device:

/usr/bin/echo ds3231 0x68 > /sys/class/i2c-adapter/i2c-1/new_device

(If you have a Raspberry Rev 1, you'd use /sys/class/i2c-adapter/i2c-0/new_device instead.)

The RTC does not store the time zone, so we need to tell the system that we'd like to use the system's time zone:

timedatectl set-local-rtc 0

And finally we copy the current system's time to the RTC chip:

hwclock -w

The RTC is now set up and ready for operation. But we're not done yet. When the system boots up, the DS3231 is unknown to the system again. We have to add a systemd service for adding it and reading the time, by creating a file called /etc/systemd/system/my-rtc.service with the following content:

[Unit]
Description=Enable battery backed-up RTC
Before=basic.target
After=sysinit.target
DefaultDependencies=no

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStartPre=-/usr/bin/bash -c '/usr/bin/echo ds3231 0x68 > /sys/class/i2c-adapter/i2c-1/new_device'
ExecStartPre=-/usr/bin/sleep 0.2
ExecStart=/usr/sbin/hwclock -s

[Install]
WantedBy=basic.target

The service is enabled via:

systemctl enable my-rtc

And now every time the system boots up, the DS3231 is added as I²C device and the system clock is set to the time found in the RTC. If a network is available, NTP will later take over and set the network time.

It's not the most elegant solution, I guess. I had to add a sleep command because it turned out that the hardware is not immediately available after adding the device. I'd like to hear from you if you found a better way.

Remember to manually use hwclock -w from time to time, to reset the RTC to the correct time. If you shut down your RasPi frequently, you could add another systemd service that automatically writes the current time on system shutdown.

R Tape loading error, Part 2

In the first part I showed how the Sinclair ZX Spectrum stored data on tape. This second part explains what is stored, and what causes a tape loading error.

The ZX Spectrum BASIC offers a SAVE command for saving all kind of data. It can be used to save a BASIC program, variable arrays, but also arbitrary parts of memory. These files are always saved in two separate blocks. The first block is called header. It contains the file name, data type, and other meta information. The second block follows about a second later and contains the data itself.

The internal structure of each block is identical. The first byte distinguishes between header ($00) and data blocks ($FF). The final byte is a parity checksum. Everything between these two bytes is the payload.

A header block always contains a payload of 17 bytes. The first byte identifies the file type, followed by the file name (10 characters), followed by the length of the data block, and closed by two optional parameters that have different meanings depending on the file type. The length and the two parameters consume two bytes each, with the lower byte coming first because the Z80 CPU is little endian.

This is an example header block of a screenshot:

00$00 = Header
0003$03 = Binary file (Code or SCREEN$)
0153S
0268h
0372r
0465e
0564d
062E.
077Az
086Fo
096En
1065e
11001BLength: 6912 bytes ($1B00)
130040Parameter 1, here: starting address ($4000)
150000Parameter 2, here: unused
20Parity

A screenshot is actually just a memory dump that starts at address $4000 (which is the starting address of the screen buffer) and is exactly 6912 bytes long (the ZX Spectrum has a resolution of 256×192 monochrome pixels plus 32×24 bytes color attributes, giving a screen buffer size of 6912 bytes).

For other file types, the two optional parameters have different meanings. For example, a BASIC program file stores the line number to start at after loading.

The final byte is the parity. It is used for error detection, and computed just by XOR-ing all the bytes that have been read. The result must be $00, otherwise a "R Tape loading error" is reported.

This kind of error detection is rather weak. Due to the nature of the XOR operation, two wrongs give a right. This means that when the block contains an even number of bad bits at the same position, they will be undetected. It is also not possible to correct reading errors, as the XOR operation only allows to identify the position of the bad bit, but not the actual byte that contained the error. More sophisticated error correction algorithms would have slowed down the loading process, though.

The parity is computed as a final step, after all the bytes have been read from the block on tape. For that reason, the loader can only decide at the end of the recording whether the loading was successful or not.

But then, why does the tape loading error sometimes appear while the block is still loading? Well, in the first part I have explained that the loading routine just reads an unknown number of bytes. It ends when waiting for a pulse change took to long. Now, if there is an audio gap on tape, the signal seems to end just in the middle of the block. It is then very likely that the parity checksum is wrong because there are still bytes missing.

Some simple copy protections made use of the way the Spectrum loads data from tape. A very common way were “headerless” files, where the header block was left out and only the data block was recorded on tape. The BASIC LOAD command was unable to read those files because of the missing header.

R Tape loading error

In the early time of home computers, at the beginning of the 1980's, hard disks and even floppy disks were too expensive for home use. The cheapest way for storing large amounts of data was the cassette tape. Cassettes and tape recorders were affordable and available in almost any household.

In this blog article, I'm going to explain how the Sinclair ZX Spectrum stored programs on cassette tapes. Other home computers of that time, like the Commodore 64 or Amstrad CPC, worked in a similar fashion.

Cassette tapes were designed to store audio signals like voice or music, so the inventors of the home computers had to find a way to convert data to audio signals. The easiest way is to serialize the data to a bit stream of 1's and 0's, and generate a long rectangular wave cycle for "1" and a short rectangular wave cycle for "0". This is what the ZX Spectrum actually does!

A short wave cycle is generated by giving power to the audio output for 855 so called T-states, and then turning off the power for another 855 T-states. A "T-state" is the time of a single clock pulse of the Z80-A CPU. As the CPU of a classic ZX Spectrum is clocked with 3.5 MHz, a T-state has a duration of 286 ns. The duration of a short wave cycle is thus 489 µs, giving an audio frequency of about 2,045 Hz. The long wave cycle is just twice as long.

Due to all kind of filters in the analog audio path, the rectangular signal is smoothed to a sinusoidal signal when played back. A Schmitt trigger inside the ZX Spectrum's hardware converts the audio signal back to a rectangular shape. Since the audio signal can have different amplitudes or could even be inverted, the hardware only cares for signal edges, not for levels. All that the loader routine now has to do is to measure the duration of the pulses, regenerate the bit stream, and put the bytes back together.

If you think that things cannot be that easy, you are right. 😄 The most difficult part for the loader is to find the start of the bit stream. If it is off by only one cycle (or even just a pulse), all the bytes are shifted by one bit, and the result is useless. All kind of noise on the tape makes it impossible to just wait for the signal to start, though.

For this reason, the recording starts with a leader signal, followed by a sync wave cycle, followed by the bit stream itself. The leader signal is just a continuous wave with a pulse length of 2,168 T-states, giving an 806 Hz tone that is displayed by red and cyan border colors on the TV. The sync wave cycle is a pulse of 667 T-States "on", followed by 735 T-states "off". After that, the actual data stream begins, which is displayed in blue and yellow border colors. When the last bit was transmitted, the data stream just ends.

So when the ZX Spectrum loads a file from tape, it first waits for the 806 Hz leader signal. If it was detected for at least 317 ms, it waits for the sync pulses, then it starts reading the bit sequence until there is a timeout while waiting for the next pulse.

It is a very simple way to store data on tape. And still, it is surprisingly reliable. After 30 years, I could recover almost all files from my old cassette tapes. Some of them were of the cheapest brands I could get my hands on back in 1987.

The only disadvantage is that this method is very slow. With 489 µs for a "0" and 978 µs for a "1", saving just 48 KBytes of data can take up to 6 minutes, giving an average bit rate of 1,363 bps (yes, bits per second). If we were to save a single 3 MBytes mp3 file that way, it would take almost 5 hours (and 5 cassettes with 60 minutes recording time each).

Some commercial games used speed loaders and copy protections. Speed loaders just reduced the number of T-states for the pulses, which increased the bit rate. Some copy protections used a "clicking" leader tone, where the leader signal was interrupted before the minimal detection time of 317 ms was reached. The original loader routine could not synchronize to these kind of signals, so it was impossible to read those files into copy programs. Those protection measures could still be circumvented by copying directly from tape to tape, but this only worked a few times due to increasing audio noise.

In the next article, I will take a deeper look at the bit stream contents, and I will also explain where the dreaded "R Tape loading error" comes from.

Premium Wall Bias Lighting, Part 3

I haven't forgotten about you. Some private stuff kept me from completing this project for a while. To make it up, I have added OpenSCAD files for a 3D printed case.

The controller was a little tricky to complete, mostly because of the very different component heights. I decided to use two circuit boards that are stacked onto each other by headers.

On the upper board, there are only the two buttons and the LCD, as well as the transistor and resistor for the LCD backlight. As I only used one-layer TriPad strip boards, I had to use this one upside down for the male headers to point downward. This rather unconventional use made it a little tricky to solder the buttons and LCD headers on the actual bottom side of the board.

The soldered controller boards. The lower board contains all the other components, as well as the wiring. The rotary encoder also made it to the lower board, because it is much taller than the other buttons. This way, the top of the button caps are almost level and nice to look at.

The result is surprisingly compact for a DIY solution. The button caps and the LCD are just perfectly positioned for a case.

With plastic feet attached, you can use the controller as it is. You can also get a plastic case with transparent top, drill three holes in it for the button caps, and mount the sandwich with spacers. But if you have the chance, you should definitely go for a 3D printed case.

I have set up a project at GitHub. It contains the circuit diagram, the bill of materials, the firmware source code, and OpenSCAD files for a printed case. There is no firmware binary yet, as you need to adapt the source code to the length of your LED strip anyway.

You will find the OpenSCAD files for the case in the GitHub project. There are bonus OpenSCAD files in the project, for printing a customized case. Due to the absence of properly layouted PCBs, I am aware that each controller is going to look differently when finished. In the parameter.scad file, you can change all kind of parameters, so you should be able to make your individual case in, well, almost any case (silly pun intended). 😄

The SPI flash memory of the Feather M0 Express is not used yet. In a future release, I may add a settings menu for the LED strip size. The controller is also forgetting all its settings when disconnected from the power. This needs to be addressed in a future release as well.

But after all, this is a start for your own DIY wall bias lighting. Feel free to send pull requests for enhancements!

Again, remember that you must remove the jumper before connecting the Feather to an USB port, otherwise your computer will be damaged.

Premium Wall Bias Lighting, Part 2

The completed prototype on a breadboard In the first part, I have assembled a working proof-of-concept for my premium wall bias lighting. Thanks to CircuitPython, it just took a couple of minutes to program a light effect once the hardware was working.

Now it's time to extend the hardware to its final stage. I'd like to have a LC display that shows the current settings. A button and a rotary encoder allows to browse through different menus and change the parameters. And finally, the strip shall be switched on and off by an illuminated power button.

Thanks to the bread board, the components were quickly added and connected to the Feather with some wires. Polling the buttons is a basic functionality of CircuitPython. It was also incredibly easy to poll the rotary encoder, because CircuitPython already comes with a library for that.

It took a lot more time to set up the LC display. CircuitPython supports SPI out of the box, but the SSD1803A controller of the display uses a weird protocol. Each command byte must be split up into two nibbles (4 bits), which are packed into bytes again, with the bit order reversed. The SPI library does not offer support for it, so I had to do all this bit mangling in Python, which turned out to become a rather ugly piece of code.

But then, finally, a minimal version of the firmware was working. I could turn the light on and off, select between two light effects, and I could also control the brightness.

However the Feather often took long breaks, where it did not react on key presses for multiple seconds. I guess the reason for that is Python's garbage collector, which stops the world while it is collecting unused objects and freeing some memory. This was actually a pretty annoying behavior that rendered the controller unusable.

After I added a third light effect, I also started to run into frequent out of memory errors. It seems that I have reached the limits of what is technically possible with CircuitPython on a Feather.

Was my approach too ambitious?

Luckily it wasn't. The Feather can also be programmed in C++, using the well known Arduino IDE. It comes with a lot of libraries that are ready to use. It's all very lightweight and is looking very promising. So why did I use Python in first place? Well, it is because I wrote my last lines of C++ code about 20 years ago. 😅

Porting the existing Python code to C++ was easier than I had expected. The SPI library now even supports reversed bit order, so it was much easier to address the LC display. On the down side, I had to test several libraries until I found a reliable one for the rotary encoder.

The C++ code consumes a fraction of the Python code's memory, so there is a lot left for extensions. The garbage collection breaks are also gone now, so the controller instantly responds to key presses. And I haven't even used the Feather's SPI flash memory yet. 😀

I have added some more light effects, and menus for adjusting brightness, saturation, and color temperature. Everything is working as expected now. It's time to finish the prototype phase and draw a circuit diagram.

R2 is the series resistor for the power button LED. A green LED would need an 68 Ω resistor at 3.3 V. However the LED is directly connected to the Feather, so the current should not exceed 7 mA (maximum rating is 10 mA). A 500 Ω resistor limits the current to a safe value. If you need more current for a fancy power LED, you can use one of the three 74HCT125 drivers left, or add a transistor.

R3 is the series resistor for the LCD backlight. The manufacturer specifies a 27 Ω resistor when the backlight LEDs are connected in series and powered with 5 V. If you use a different backlight, change the resistor accordingly. The BC 548 transistor permits up to 100 mA in this configuration.

Remember: You must remove the jumper JP1 before connecting the Feather to an USB port, or your computer will be damaged.

In the next part, I'm going to grab my soldering iron and build a final version. It's high time. The many wires on the breadboard prototype are annoying when operating the rotary encoder. Also its pins are too short and are often disconnecting from the breadboard when I use it.