overlay64

programmierbares Video-Overlay Modul

Overlay64 Rev.1

Das Overlay64-Modul ermöglicht das Einblenden benutzerdefinierter Texte auf einem vorhandenen analogen Videosignal in Abhängigkeit der Schaltzustände von bis zu 24 digitalen Eingangs- und Kontrollleitungen.

So kann zum Beispiel der Zustand diverser Hardware-Erweiterungen in einem klassischen Heimcomputer direkt auf dem Bildschirm mit eingeblendet werden:

Einsatz im C64 zur Anzeige des Schaltzustandes von Multirom-Adapter und Stereo-SID-Board

Der Benutzer schreibt eine einfache Konfigurationsdatei, die bestimmt, welche Texte bei welchen spezifischen Zuständen von Eingangsleitungen an welchen Stellen auf dem Bildschirm eingeblendet werden sollen. Die Datei wird mit Hilfe des mitgelieferten Konfigurationstools in ein Binärformat übersetzt und in den EEprom-Speicher des Mikrokontrollers übertragen. Das Konfigurationstool wird unter Linux, MacOSX und Windows unterstützt.

Das Modul ist primär für den Einsatz in Heimcomputern gedacht und kann dort der Anzeige von Schaltzuständen von Zusatzhardware wie dem MixSID oder dem Reprom64 dienen. Es kann allerdings überall dort eingesetzt werden, wo die textuelle Anzeige digitaler Schaltzustände auf einem analogen Videosignal benötigt wird.

Dokumentation

Downloads

Quelltexte

Die Quelldistribution enthält die Quelltexte der Firmware und des Konfigurationstools sowie Schaltplan und Platinenlayout im KiCAD-Format.

Die letzte stabile Version ist overlay64-1.2.tar.gz.

Alle veröffentlichten Versionen finden sich unter /download/overlay64

Neuste Entwicklungen können auf github verfolgt werden:

git clone https://github.com/hbekel/overlay64

Binärdateien

Schaltplan

Bestellung von Bausätzen

Ich biete Bausätze zum Preis von 25€ pro Stück an. Der Bausatz enthält die Platine, einen vorprogrammierten Atmega1284 und alle weiteren benötigten Teile (ausgenommen Verbindungskabel). Weltweiter Versand per Post ist kostenlos.

Bestellungen könnt Ihr per Mail an henning.liebenau@protonmail.com tätigen.

Bitte verwendet das Wort “overlay64” im Betreff. Gebt in der Mail euren vollen Namen, Eure Lieferadresse und die Anzahl der gewünschten Bausätze an. Bitte beachtet, dass die Anzahl der Bausätze pro Person auf zwei Stück beschränkt ist. Ihr bekommt dann von mir per Mail weitere Informationen zur Bezahlung per Überweisung. Bitte beachtet, dass im voraus gezahlt werden muss, um die Bestellung verbindlich zu bestätigen.

Hinweise zur Verfügbarkeit

Ich versuche stets eine ausreichende Menge an Bausätzen auf Lager zu halten. Bitte beachtet jedoch, dass dies mit geringem Budget und bei minimaler Gewinnmarge in meiner Freizeit passiert. Mein Ziel ist es primär, der Community meine Hardware zugänglich zu machen, und nicht etwa ein profitables Geschäft zu betreiben.

Sollte ich also momentan keine Bausätze auf Lager haben kann es durchaus einige Wochen dauern, bis ich eine neue Serie von Bausätzen produzieren und somit eurer Bestellung nachkommen kann. Unter Umständen muss ich auch warten, bis eine ausreichende Anzahl an Vorbestellungen eingeht, bevor ich selbst die nötigen Bauteile zu einem ausreichend günstigen Preis bestellen kann. In diesen Fällen werde ich Euch natürlich regelmäßig über den Status Eurer Bestellung informieren. Es bedarf also unter Umständen ein wenig Geduld und auch Vertrauen von Eurer Seite.

Aufbau

Der Aufbau sollte problemlos zu bewerkstelligen sein, haltet Euch einfach an die unten stehende Bauteilliste und den Bestückungsplan.

Falls ein möglichst flacher Aufbau gewünscht ist, können die ICs auch ohne Sockel eingebaut werden. Allerdings sollte in diesem Falle sichergestellt werden, dass der Atmega einen funktionierenden Bootloader enthält, da sich kein JTAG-Header auf der Platine befindet.

Benötigte Bauteile

Referenz Typ Wert Bauweise/RM
IC1 Atmega1284(P) - DIP40 15.24mm
U1 LM1881 - DIP8 7.62mm
C2 Keramik-Kondensator 18pF 2.5mm
C3 Keramik-Kondensator 18pF 2.5mm
C1 Keramik/Film-Kondensator 100nF 2.5mm
C4 Keramik/Film-Kondensator 100nF 2.5mm
C5 Keramik/Film-Kondensator 100nF 2.5mm
C6 Keramik/Film-Kondensator 100nF 2.5mm
D1 Zener Diode (low power) 3.6V 500mW DO-204
D2 Zener Diode (low power) 3.6V 500mW DO-204
R1 Präzisionswiderstand 68 6.5mm, ∅ 2.5mm
R2 Präzisionswiderstand 68 6.5mm, ∅ 2.5mm
R3 Präzisionswiderstand 1k5 6.5mm, ∅ 2.5mm
R5 Präzisionswiderstand 680k 6.5mm, ∅ 2.5mm
RV1 Trimpotentiometer 1k T7YA oder 3339P
∅ 7mm, Höhe 6mm, RM 2.54mm
P1 USB Mini-B Buchse - Printmontage
P2 Gewinkelte Stiftleiste 1x16 2.54mm
P9 Gewinkelte Stiftleiste 1x16 2.54mm
P3 Gewinkelte Stiftleiste 1x8 2.54mm
P4 Gewinkelte Stiftleiste 1x3 2.54mm
SW1 Taster - 6x6mm print
Y1 Quartz 20Mhz HC49/U-S
- DIP-Sockel 40-polig - DIP40 15.24mm
- DIP-Sockel 8-polig - DIP8 7.62mm

Bestückungsplan

Installation der Firmware

Falls Ihr einen Bausatz von mir erworben habt, ist der Atmega bereits vollständig programmiert und einsatzbereit. Fahrt in diesem Fall direkt mit Einbau und Test fort.

Falls Ihr ansonsten keine Möglichkeit habt, einen Atmega selbst zu programmieren, könnt Ihr mir den Atmega zusenden und ich bereite ihn für Euch vor. Mailt mir einfach unter henning.liebenau@protonmail.com

Installation des kombinierten Firmware-Images

Die einfachste Möglichkeit besteht darin, das kombinierte Firmware-Image aufzuspielen. Es enthält bereits den Bootloader und die Firmware und kann mit einem externen Programmiergerät (z.B. dem TL866) aufgespielt werden.

Dabei muss darauf geachtet werden, die korrekten Werte für die Fuses des Atmega zu verwenden:

    Low:      0xd7
    High:     0xd0
    Extended: 0xfc

Diese Werte entsprechen den zu setzenden Fuses SUT1, CKSEL3, SPIEN, EESAVE, BOOTSZ0, BOOTSZ1, BOOTRST, BODLEVEL0 und BODLEVEL1. Alle anderen Fuses dürfen nicht gesetzt sein.

Manuelle Installation des Bootloaders

Der Atmega1284p benötigt den USBaspLoader, der vor Einbau auf der Platine über ISP programmiert werden muss.

In der Quelldistribution findet sich eine vorkonfigurierte Version des Bootloaders.

Im Verzeichnis bootloader müssen die PROGRAMMER-Optionen in der Datei Makefile.inc für das verwendete Programmiergerät angepasst werden. Dann kann aus diesem Verzeichnis heraus der Bootloader kompiliert und geflasht werden sowie die Fuses gesetzt werden:

 $ make flash fuse

Der Atmega kann nun in das Modul eingesetzt werden. Bei aktiviertem Bootloader identifiziert sich das Gerät gegenüber dem PC mit

16c0:05dc Van Ooijen Technische Informatica shared ID for use with libusb

Es kann mit avrdude wie folgt angesprochen werden:

avrdude -p m1284p -c usbasp <commands...>

Zuvor müssen jedoch die USB-Geräte auf dem PC konfiguriert werden.

Aktivieren des Bootloaders

Der Bootloader kann über USB mit folgendem Befehl aktiviert werden:

$ overlay64 boot

Um den Bootloader manuell zu aktivieren muss während des Einschaltens der Taster BOOT gedrückt werden und kurz nach dem Einschalten wieder losgelassen werden.

Installation und Aktualisierung der Anwendung

Sobald einmal ein funktionierender Bootloader und eine funktionierende Anwendung aufgespielt sind kann danach der folgende Befehl benutzt werden, um die Anwendung zu aktualisieren:

$ overlay64 update overlay64-firmware-1.2.hex

Es wird automatisch der Bootloader aktiviert, die Anwendung aktualisiert und gestartet.

Sollte diser Befehl aus irgend einem Grund fehlschlagen, z.B. wenn die Anwendung nicht mehr richtig funktioniert, so kann der Bootloader immer noch manuell aktiviert werden und die Anwendung kann dann mit folgendem Befehl aktualisiert werden:

$ avrdude -p m1284p -c usbasp -U flash:w:overlay64-firmware-1.2.hex

Wer die Anwendung selbst kompiliert kann alternativ auch das target program des Toplevel-Makefiles verwenden.

Die Fimware Version 1.1 enthält einen Fehler, der das Erkennen der USB-Geräte unter bestimmten Versionen von Windows beeinträchtigen kann. Windows meldet die Geräte dann sporadisch als unbekannt oder nicht funktionsfähig. In diesem Fall kann der LM1881 vorübergehend entfernt werden. Ohne den LM1881 wird das Overlay64 keine Anzeige erzeugen, die USB-Geräte sollten aber nun auch verlässlich erkannt werden, so dass die Firmware mit dem hier gezeigten Befehl aktualisiert werden kann.

Einbau und Test

Die Pins an der unteren linken Ecke der Platine müssen mit der Spannungsversorgung und dem zu überlagernden Videosignal verbunden werden.

Spannungsversorgung

VCC muss an +5V Gleichspannung angeschlossen werden. GND muss so nahe wie möglich am Videosignal angeschlossen werden. Ist die Verbinding zu GND deutlich länger oder wird eine Schleife gebildet, kommt es besonders bei dunklem Hintergrund zum Verlust der Video-Synchronisation.

VCC und GND müssen aus derselben Quelle stammen, aus der auch die Schaltung zur Erzeugung des Vidosignals sowie die Eingangs- und Kontrollleitungen gespeist werden.

Videosignal

Der mit VIDEO gekennzeichnete Pin muss mit dem zu überlagernden Videosignal verbunden werden.

Dies ist entweder der Luminanz-Teil eines S-Video-Signals oder ein Composite-Signal (FBAS/CVBS).

Commodore C64

Der C64 gibt sowohl ein S-Video-Signal (Chrominanz/Luminanz) als auch ein Composite-Signal (FBAS/CVBS) an der Audio/Video-Anschlussbuchse aus.

Das Videosignal des Overlay64 kann entweder zur S-Video-Ausgabe, zur Composite-Ausgabe oder zu beiden Ausgaben gleichzeitig hinzugefügt werden.

Nur S-Video

Um das Signal nur zur S-Video-Ausgabe hinzuzufügen wird der VIDEO-Pin mit dem an Pin 1 der A/V-Buchse verfügbaren Luminanz-Signal verbunden.

Wer das Luminanz-Signal nicht direkt an der A/V-Buchse sondern an anderer Stelle auf der Hauptplatine abgreifen möchte muss darauf achten, nur das Luminanz-Signal zu verwenden, das von HF-Modulator-Schaltung geliefert wird.

In keinem Fall darf das vom VIC gelieferte, unverstärkte Luminanz-Signal direkt verwenden werden.

Nur Composite

Um das Signal zur Composite-Ausgabe hinzuzufügen reicht es aus, den VIDEO-Pin mit Pin 4 der A/V-Buchse zu verbinden. Das Signal ist hier allerdings insgesamt schwächer und schwankt zudem leicht mit der Helligkeit des zu überlagernden Signals.

S-Video und Composite gleichzeitig (mit Einschränkungen)

Soll das Signal sowohl zur S-Video-Ausgabe als auch zur Composite-Ausgabe hinzugefügt werden, so muss der VIDEO-Pin mit dem Emitter des Luminanz-Transistors der HF-Modulator-Schaltung verbunden werden.

Diese Lösung ist jedoch nicht optimal. Die Anzeige wird insgesamt weniger hell und kann unter Umständen die Video-Synchronisation stören, besonders wenn das zu überlagernde Signal bereits helle Bereiche enthält. Diese Option also nur verwenden, wenn sie unbedingt erforderlich ist.

Hier sind die Schaltpläne der im C64 verwendeten Varianten der HF-Modulator-Schaltung. Die roten Punkte markieren jeweils den geeigneten Anschlusspunkt.

Da es im Aufbau mehr als zwei Varianten der Schaltungen gibt sollte der Anschlusspunkt vor Inbetriebnahme sicher lokalisiert werden.

Test

Sind Spannungsversorgung und Video-Signal verbunden, sollte zunächst das Trimpoti für die Helligkeit in Mittelstellung gebracht werden.

Nun kann das Gerät eingeschaltet werden.

Da noch keine benutzerdefinierte Konfiguration aufgespielt wurde sollten nun einige Zeilen Text aus der Standard-Konfiguration angezeigt werden:

Einstellen der Helligkeit

Mit Hilfe des Potis kann die Helligkeit des eingemischten Signals eingestellt werden. Je weiter das Poti nach rechts gedreht wird, desto heller erscheint die Anzeige.

Allerdings wird bei zunehmender Stärke des zugemischten Signals irgendwann das vorhandene Signal so weit gestört, das die Synchronisation verloren geht.

Einrichten der USB-Geräte auf dem PC

Das Overlay64-Modul implementiert zwei verschiedene USB-Geräte, je nachdem, ob der Bootloader oder die Anwendung gerade aktiv ist.

Während des normalen Betriebs kann das Overlay64-Gerät mit Hilfe des Konfigurationstools angesprochen werden. Dieses Gerät identifiziert sich gegenüber dem PC mit den folgenden Eigenschaften:

Vendor OpenMoko, Inc.
Manufacturer Henning Bekel
Device Overlay64
Vendor ID 1d50
Product ID 6100

Im Bootloader-Modus wird das USBasp-Programmiergerät emuliert. Dieses Gerät identifiziert sich gegenüber dem PC mit den folgenden Eigenschaften:

Vendor Van Ooijen Technische Informatica shared ID for use with libusb
Manufacturer www.fischl.de
Device USBasp
Vendor ID 16c0
Product ID 05dc

Linux

Unter Linux werden die benötigten udev-Regeln zusammen mit dem Konfigurationstool installiert. Nach der Installation muss der folgende Befehl ausgeführt werden, um die Geräte sofort benutzen zu können:

# udevadm control --reload-rules

Im Bootloader-Modus erscheint das entsprechende Gerät als symlink unter /dev/usbasp. Im Normalbetrieb wird das entsprechende Gerät als symlink unter /dev/overlay64 angelegt. Diese symlinks werden mit den Dateiberechtigung 0666 angelegt und können so von jedem Benutzer verwendet werden. Um den Zugriff zu beschränken können die jeweiligen Regeln in /etc/udev/rules.d/10-overlay64.rules angepasst werden.

Windows

Wird unter Windows eines der USB-Geräte zum ersten mal angeschlossen, versucht Windows, einen Treiber für dieses Gerät herunterzuladen und zu installieren. Da es sich bei beiden Geräten jedoch um treiberlose Geräte handelt, ist dieser Versuch sinnlos, da es schlicht keine speziellen Treiber für diese Geräte gibt. Die Windows-Treiberinstallation muss abgebrochen werden, da Windows ansonsten den Zugriff auf diese Geräte dauerhaft verhindert, da es aus seiner Sicht keine brauchbaren Treiber finden konnte.

Stattdessen muss das frei erhältliche Tool Zadig verwendet werden. Dieses generiert minimale Treiber, die die Geräte lediglich mit den für den generischen Zugriff benötigten Bibliotheken verknüpfen.

Wird Zadig nun ausgeführt, sollte es das Gerät “Overlay64” erkennen. Es ist der “WinUSB” Treiber für dieses Gerät zu installieren. Die benötigte libusb-1.0.dll wird mit dem Konfigurationstool installiert.

Nun muss noch einmal in den Bootloader-Modus gewechselt werden, um auch für dieses Gerät (USBasp) einen Treiber zu installieren. Hier wird ebenfalls der “WinUSB”-Treiber verwendet.

Für den Fall, dass das USBasp-Gerät über avrdude und nicht über das overlay64-tool verwendet werden soll, muss unter Umständen der Zadig-Treiber “libusb-win32” installiert werden, da die für Windows erhältlichen Versionen von avrdude meist noch gegen die veraltete libusb-0.1 gelinkt sind, deren Verwendung nur durch Zadigs libusb-win32-Treiber möglich ist.

Installation des Konfigurationstools overlay64

Binäres Installationspaket (Windows)

Die Windows-Version kann mit Hilfe des Win32-Installationspaketes installiert werden. Dieses installiert auch die benötigte libusb-1.0.dll und fügt das Installationsverzeichnis zur Umgebungsvariable PATH hinzu, so dass die overlay64.exe in der Eingabeaufforderung aus jedem beliebigen Verzeichnis heraus aufgerufen werden kann.

Kompilieren und Installieren aus den Quelltexten

Linux & MacOSX

libusb-1.0 und das entsprechende “devel”-Packet (falls bei eurer Distribution benötigt) müssen auf dem System vorhanden sein.

$ tar vxzf overlay64-1.2.tar.gz
$ cd overlay64-1.2
$ make
$ make install

Dies installiert nach erfolgreicher Kompilierung das Konfigurationstool overlay64 nach /usr/local/bin. Die PREFIX-Variable kann für die Installation mit einem anderen Präfix benutzt werden, z.B. installiert make PREFIX=/usr install nach /usr/bin. Die Variable DESTDIR kann für die Installation in ein lokales Verzeichnis mit dem gegebenen Präfix verwendet werden.

Unter Linux werden die benötigten udev-Regeln nach /etc/udev/rules.d/ installiert. Nach der Installation sollte als root-Benutzer zusätzlich der folgende Befehl ausgeführt werden:

# udevadm control --reload-rules

Windows

Falls Cygwin verwendet wird kann eine Windows-Version auf die gleiche Weise kompiliert und installiert werden wie unter Linux oder MacOSX. Die benötigten Cygwin-Pakete sind libusb-1.0 und libusb-1.0-devel. Die resultierende Anwendung benötigt jedoch weiterhin Cygwin-spezifische Bibliotheken (siehe ldd overlay64.exe).

Eine native Win32-Anwendung kann mit Hilfe der Cross-Compiler-Suite Mingw32 unter Linux oder Cygwin kompiliert werden. Falls nötig ist dazu das Makefile zu editieren und die MINGW32-Variable entsprechend des benötigten Präfixes für eure Mingw32-Installation anzupassen. Dann kann mit Hilfe von make win32 die overlay64.exe gebaut werden.

Konfiguration

Die Konfigurationsdatei ist eine einfache Textdatei. Das Konfigurationstool overlay64 konvertiert diese Datei in ein internes binäres Format und programmiert damit den EEprom-Speicher des Mikrokontrollers. Siehe Befehl configure.

Überblick

Die Konfiguration bestimmt, welche Texte wo und in Abhängigkeit von welchen Eingangsleitungen und deren Zuständen angezeigt werden sollen. Ebenso bestimmt sie, wann überhaupt Text angezeigt werden soll, entweder kurzzeitig und automatisch, sobald sich der Zustand der überwachten Eingangsleitungen ändert, oder aber manuell, abhängig vom Zustand extern angesteuerter, benutzerdefinierter Kontrollleitungen.

Die Konfiguration kann dabei in mehrere voneinander unabhängige Bereiche aufgeteilt werden, so dass unterschiedliche Anzeigen und Verhaltensweisen realisiert werden können.

Anhand des folgenden allgemeinen Beispiels sollen die verschiedenen Möglichkeiten kurz skizziert werden:

screen manual

  sample 0
    when 0
      write 0 10 "EINGANG 0 IST LOW "
    when 1
      write 0 10 "EINGANG 0 IST HIGH"

screen notify

  write 0 0 "DIES IST DER ZWEITE SCREEN"

  sample 1 2
    when 00 write 1 10 "BEIDE EINGAENGE SIND LOW             "
    when 01 write 1 10 "EINGANG 1 IST LOW, EINGANG 2 IST HIGH"
    when 10 write 1 10 "EINGANG 1 IST HIGH, EINGANG 2 IST LOW"
    when 11 write 1 10 "BEIDE EINGAENGE SIND HIGH            "

control 16 manual 0
timeout 100

Die erste Anweisung screen kennzeichnet den Begin eines Screens, der in diesem Fall im manuellen Modus betrieben wird (manual). Ein Screen ist ein Bereich der Konfiguration, der unabhängig von anderen Screens angezeigt und kontrolliert werden kann. Manueller Modus bedeutet in diesem Fall, dass der Screen nur angezeigt wird, wenn eine andere, als Kontrolleitung definierte Leitung durch externe Ansteuerung aktiviert wird.

Der erste Screen enthält eine Sample-Anweisung (eng. sample = Messung), die in diesem Fall lediglich die erste Eingangsleitung (Leitung 0) überwacht. Sample-Anweisungen müssen für einen oder mehrere Zustände der von ihnen überwachten Eingangsleitungen eine oder mehrere Anweisungen enthalten, die bei Eintreten dieses Zustandes ausgeführt werden sollen. Diesen Anweisungen wird die dem Zustand entsprechende when-Klausel vorangestellt.

Der Befehl write schreibt schließlich den angegebenen Text an der mit Reihe und Spalte angegebenen Position auf den Bildschirm.

Ist also der erste Screen aktiviert, wird die Leitung 0 laufend überwacht. Ist diese High, wird der Text “EINGANG 0 IST HIGH” ab Zeile 0, Spalte 10 auf den Bildschirm geschrieben. Ist die Leitung low, wird entsprechend “EINGANG 0 IST LOW” an die gleiche Stelle geschrieben.

Die nun folgende zweite screen-Anweisung markiert den Beginn des nächsten Screens. Dieser ist auf notify (to notify = benachrichtigen, hinweisen) gesetzt, so dass er nur für eine bestimmte, über die Anweisung timeout definierte Anzahl von Frames angezeigt wird, sobald sich der Zustand einer der von den Sample-Anweisungen innerhalb dieses Screens überwachten Leitungen ändert.

Die Sample-Anweisung in diesem screen überwacht die Eingangsleitungen 1 und 2 gleichzeitig. Der Zustand dieser Leitungen wird zu einem zwei Bit breiten Wert zusammengefasst. Entsprechend werden die when-Klauseln für alle vier möglichen Werte angegeben.

Die control-Anweisung definiert nun die Eingangsleitung 16 als eine low-aktive, manuelle Kontrolleitung für den ersten Screen. Solange diese Leitung auf low gezogen wird, ist der Screen aktiviert, die darin enthaltenen Samples werden verabeitet und der Text entsprechend angezeigt.

Kontrollleitungen können hier auch im notify-Modus betrieben werden, so dass eine steigende Flanke auf dieser Leitung den assoziierten Screen nur für die mit timeout angegebene Anzahl von Frames aktiviert.

Die timeout-Anweisung definiert den globalen timeout-Wert für alle im notify-Modus betriebenen Screens bzw. Kontrolleitungen. Er wird als Anzahl von Frames angegeben, sodass bei einem PAL-Signal 50 frames einer Verzögerung von einer Sekunde entsprechen.

Screens können auch write-Befehle außerhalb von Sample-Anweisungen enthalten. Diese Befehle werden unabhängig vom Zustand von Eingangsleitungen ausgeführt, solange der Screen aktiviert ist.

Allgemein werden die write-Befehle mehrerer gleichzeitig aktivierter Screens in der Reihenfolge abgearbeitet, in der sie in der Konfigurationsdatei definiert wurden. Schreiben zwei aktivierte Screens in dieselbe Zeile, wird nur der durch die write-Befehle des zuerst definierten Screens geschriebene Text sichtbar.

Es gibt einen weiteren Screen-Modus always, in dem der Screen immer aktiviert wird, unabhängig von aktuellen Zustand von Kontroll- oder Eingangsleitungen.

Jedoch gilt die allgemeine Regel, dass ein Screen nur dann aktiviert wird, wenn dies zur Auführung mindestens einer effektiven Schreiboperation führen würde, und zwar unabhängig davon, ob der screen bereits über eine der oben aufgeführten Regeln aktiviert wurde.

Kontrollleitungen können auch mehrere Screens gleichzeitig aktivieren.

Allgemeine Regeln sowie die genaue Syntax der einzelnen Anweisungen werden im nächsten Abschnitt ausführlich beschrieben.

Syntax

Leerzeichen und Kommentare

Leerzeichen sind nur zur Trennung von Elementen signifikant. Leerzeilen und überzählige Leerzeichen vor oder hinter Elementen werden ignoriert.

Kommentare werden mit einem Nummernzeichen # eingeleitet und erstrecken sich bis zum Ende der Zeile.

Symbole

Benutzerdefinierte Symbole können die Flexibilität und Lesbarkeit der Konfiguration erhöhen. Sie werden in Form von Schlüssel/Wert-Paaren definiert:

<Name> = <Wert>

Symbolnamen dürfen nur aus alphanumerischen Zeichen, Ziffern oder Unterstrichen bestehen. Falls ein Symbolame einem reservierten Schlüsselwort entspricht wird eine Warnung ausgegeben.

Sobald ein Symbol definiert wurde, wird jeder im folgenden Text erscheinende Symbolname durch den zugeordneten Wert ersetzt. Wird ein Symbol im Text vor seiner Definition benutzt, wird eine entsprechende Fehlermeldung ausgegeben.

Zeichenketten

Zeichenketten werden durch doppelte Anführungszeichen eingefasst und müssen auf derselben Zeile geöffnet und wieder geschlossen werden. Die folgenden Escape-Sequenzen können innerhalb einer Zeichenkette verwendet werden:

\" fügt ein literales Anführungszeichen ein

\\ fügt einen literalen Backslash ein

Anweisungen

screen

screen [<Modus>]

Leitet einen neuen Screen-Bereich ein und setzt den Betriebsmodus für diesen Screen. Screen-Bereiche können in anderen Anweisungen über ihren Index referenziert werden, wobei der erste in der Konfigurationsdatei definierte Screen mit 0 indiziert ist.

Als Modus wird entweder manual (manuell), notify (Hinweis) oder always (immer) angegeben. Wird kein Modus angegeben so wird manual angenommen.

Im manuellen Modus kann der Screen-Bereich nur explizit durch eine entsprechend definierte Kontrollleitung aktiviert werden (control).

Im Notify-Modus wird der Screen automatisch für timeout Frames aktiviert, sobald sich der Zustand einer der innerhalb dieses Screens überwachten Eingangsleitungen ändert.

Im Modus Always wird der Screen immer aktiviert, unabhängig vom aktuellen Zustand von Eingangs- oder Kontrollleitungen, jedoch nur dann, wenn die folgende Regel ebenfalls zutrifft:

Unabhängig vom gewählten Modus wird ein Screen immer nur dann aktiviert, wenn mindestens eine effektive Schreiboperation daraus resultieren würde, nachdem die obigen Regeln angewandt wurden.

control

control <Leitung> <Modus> <Screen...>

Definiert eine Eingangsleitung als externe digitale Kontrollleitung, die die angegebenen Screens im angegebenen Modus aktiviert.

Als Modus muss entweder manual (manuell) oder notify (Hinweis) angegeben werden.

Im manuellen Modus wird die Leitung zu einer low-aktiven Kontrolleitung, die die angegebenen Screens aktiviert, solange die Leitung auf low gezogen wird.

Im Notify-Modus werden die angegebenen Screens bei steigender Flanke für timeout Frames aktiviert.

sample

sample <Leitung...>

Bewirkt, dass eine oder mehrere Eingangsleitungen überwacht und ihr Zustand zu einem binären Wert kombiniert werden, wobei die erste angegebene Leitung als höchstwertigstes Bit verwendet wird. Sample-Anweisungen dürfen nicht außerhalb von Screen-Bereichen stehen.

when

when <Wert>

Die direkt auf diese Anweisung folgenden Befehle werden nur ausgeführt, wenn der angegebene Wert dem Zustand der aktuell durch den zugehörigen Sample-Bereich überwachten Eingangsleitungen entspricht.

Der Wert wird als Binärwert angegeben und darf nur 0 für low und 1 für high enthalten. Der Wert muss eine Stelle für jede der aktuell überwachten Leitungen enthalten.

write

write <Zeile> <Spalte> "<Text>"

Schreibt den angegebenen Text in die angegebene Zeile, beginnend in der angegebenen Spalte.

Es stehen insgesamt 30 Zeilen zur Verfügung, die von 0 bis 29 indiziert werden. Jede Zeile besteht aus 53 Spalten, die von 0 bis 52 indiziert werden.

Die Zeichenkette darf nur druckbare 7-Bit ASCII-Zeichen enthalten (ASCII-Codes 32-127). Ergebnisse für Codes jenseits von 127 sind nicht definiert.

Siehe Zeichenketten bezüglich weiterer Einschränkungen.

timeout

timeout <frames>

Die timeout-Anweisung setzt die Dauer für die Anzeige von Screen-Bereichen, die durch Screens oder Kontrollleitung im Notify-Modus ausgelöst werden.

Die Dauer wird als Anzahl der Video-Frames angegeben. Bei einem 50Hz PAL-Signal entsprechen 50 Frames einer Dauer von einer Sekunde. Bei einem NTSC-Signal mit 60Hz entsprechen 60 Frames einer Dauer von einer Sekunde.

Verwendung des Konfigurationstools overlay64

Das Programm overlay64 ist ein Kommandozeilenprogramm. Bei Aufruf ohne weitere Argumente wird die folgende Synopsis angezeigt:

overlay64 v1.1
Copyright (C) 2016 Henning Bekel.
License GPLv3: GNU GPL version 3 <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Usage:
      overlay64 <options>
      overlay64 [configure] <infile|->
      overlay64 convert [<infile>|-] [<outfile>|-]
      overlay64 update <firmware>
      overlay64 font-convert <infile> <outfile>
      overlay64 font-update <infile>
      overlay64 identify
      overlay64 boot
      overlay64 reset

  Options:
      -v, --version : print version information
      -h, --help    : print this help text

  Commands:
      configure    : read/parse configuration and flash to eeprom
      convert      : convert configuration to/from binary/text format
      update       : update firmware from Intel HEX file
      font-convert : convert C64 charset to overlay64 font file
      font-update  : install font from overlay64 font file
      identify     : report firmware version and build date
      boot         : make device enter bootloader mode
      reset        : reset device (leave bootloader/restart application)

  Files:
      <infile>   : input file, format is autodetected
      <outfile>  : output file, format determined by extension
      <firmware> : firmware in binary or Intel HEX format (.bin or .hex)

      *.conf : plain text config file format
      *.bin  : binary file format (default)
      *.hex  : Intel HEX file format
      -      : standard input/output


Optionen

--help zeigt die obige Synopsis an

--version zeigt die Versions-, Copyright- und Lizenzinformationen an

Befehle

Datei als einziges Argument

overlay64 <Datei>

Ist das einzige Argument ein Pfad zu einer existierenden Datei, so entspricht dies dem Aufruf

$ overlay64 configure <Datei>

configure

overlay64 configure <Datei|->

Übertragt die angegebene Konfigurationsdatei zum Gerät.

Die angegebene Datei kann entweder eine Konfigurationsdatei im Textformat oder eine zuvor mit dem Befehl convert erzeugte Binärdatei sein.

Eine Textdatei wird zunächst in das Binärformat konvertiert. Dann wird die binäre Konfiguration in den EEProm-Speicher der Mikrokontrollers übertragen. Danach wird das Modul zurückgesetzt, so dass die aktuelle Konfiguration verwendet wird.

convert

overlay64 convert <Eingabedatei|-> <Ausgabedatei|->

Konvertiert Konfigurationsdateien aus oder in das Text- oder Binärformat.

Ist die Eingabedatei im Textformat, wird sie ins Binärformat konvertiert. Handelt es sich um eine Binärdatei, wird sie in das Textformat zurück konvertiert.

update

overlay64 update <firmware>

Versetzt das Modul in den Bootloader-Modus, aktualisiert Firmware aus der angegebenen Datei und setzt das Modul zurück.

Die Firmwaredatei kann entweder eine Intel-HEX-Datei mit der Endung .hex oder eine Binärdatei mit der Endung .bin sein.

font-convert

overlay64 font-convert <Eingabedatei> <Ausgabedatei>

Konvertiert eine C64-Zeichensatz-Datei in eine overlay64-Font-Datei. Kopiert nur diejenigen Zeichen, die sowohl im ASCII- als auch im PETSCII-Encoding vorkommen. Die übrigen ASCII-Zeichen wie Backtick, Tilde, Zirkumflex etc werden aus dem Standard-Font des overlay64 kopiert.

Die resultierende Datei kann mit einem beliebigen 8-Bit-Fonteditor bearbeitet werden.

font-update

overlay64 font-update <Eingabedatei>

Überträgt die angegebene overlay64-Font-Datei über USB zum Modul und setzt das Modul zurück. Es werden nur die ersten 768 bytes (96 Zeichen) der angegebenen Datei übertragen.

boot

overlay64 boot

Versetzt das Modul über einen USB-Befehl in den Bootloader-Modus.

reset

overlay64 reset

Setzt das Modul zurück. Verlässt den Bootloader-Modus oder startet die Anwendung neu.

identify

overlay64 identify

Identifiziert das Modul bzw. dessen Betriebsmodus. Im Normalbetrieb wird die Version der Anwendung und das Kompilationsdatum ausgegeben. Ist der Bootloader aktiv, wird dessen Version ausgegeben.

Standard Ein- und Ausgabe

Kann für einen Befehl statt eines Dateinamens ein einzelner Bindestrich - angegeben werden, so wird dadurch die Standard-Ein- bzw. Ausgabe verwendet.

Font-Format und Einschränkungen bei der Darstellung

Dateiformat

Font-Dateien sind Binärdateien, die die Bitmuster von 96 8x8 großen Zeichen enthalten. Diese Zeichen entsprechen den ASCII-Codes 32-127 (also allen druckbaren 7-Bit-ASCII-Zeichen). Als solche kann die Datei mit beliebigen, für 8x8 große Bitmap-Zeichen geeigneten Editor bearbeitet werden.

Der font-update-Befehl akzeptiert auch größere Dateien, allerdings werden immer nur die ersten 96 Zeichen (768 bytes) zum Modul übertragen.

Einschränkungen bei der Darstellung

Bei der Darstellung verbleibt eine kleine, ungefähr einen Pixel breite Lücke zwischen dem vorhergehenden und dem folgenden Zeichen. Die Ausgabeleitung der Mikrokontrollers ändert ihren Zustand während dieser Lücke nicht, so dass sie in dem Zustand verbleibt, der durch das letzte Bit des Zeichens auf der aktuellen Zeile gesetzt wurde. Mit anderen Worten wird die letzte Spalte des 8x8 Pixel großen Zeichens tatsächlich zwei Pixel breit dargestellt. Daher sollte die letzte Zeile für gewöhnlich leer bleiben, zumindest bei dem in der 53ten Spalte angezeigten Zeichen, da sonst die Video-Syncronisation verloren geht.

In den in der Quelldistribution mitgelieferten Fonts ist die rechte Spalte der enthaltenen Zeichen daher nie gesetzt.

Diese Einschränkung sollte bei der Konvertierung von C64-Zeichensätzen mit dem font-convert-Befehl beachtet werden.

Lizensierung

Copyright (C) 2016 Henning bekel <h.bekel@googlemail.com>

Hardware lizensiert unter CERN OHL v.1.2, siehe ./hardware/LICENSE.txt
Software und Firmware lizensiert unter GNU GPLv3, siehe ./LICENSE

Die Software enthält Code unter MIT-Lizenz, veröffentlicht unter https://github.com/arkku/ihex, zum Lesen von Intel HEX Dateien, copyright (C) 2013-2015 Kimmo Kulovesi, siehe ./intelhex/LICENSE

Die Firmware enthält den V-USB-Treiber (https://www.obdev.at/vusb), (C)2008 Objective Development GmbH.

Im ./bootloader-Verzeichnis befindet sich der Quelltext des USBasp bootloaders, (C)2013 Stephan Baerwolf (matrixstorm@gmx.de) und (C)2008 Objective Development GmbH (https://www.obdev.at/vusb).

Gemäß den Bedingungen der (identischen) Lizenzen für den V-USB-Treiber und den USBasp-Bootloader (./firmware/usbdrv/License.txt und ./bootloader/License.txt, ist das gesamte Projekt veröffentlicht unter

http://www.henning-bekel.de/overlay64

Die Distribution enthält entprechend der o.g. Lizenzbedingungen:

Die Produkt- und Hersteller-USB-IDs für das Overlay64 USB-Gerät wurden freundlicherweise von OpenMoko, Inc bereitgestellt (http://openmoko.org).