Firmware- und FPGA-Update

Grundsätzliches

Die HX3-Platine erlaubt es, die unter Bugfixes beschriebenen Updates über ein serielles USB-Adapterkabel selbst aufzuspielen. Keine Angst, Sie können die Hardware damit nicht beschädigen; falls doch etwas schief geht, können wir Ihnen die Platine jederzeit wieder neu programmieren. Sollten Sie sich das Update nicht zutrauen, können Sie die Platine auch einsenden und im Keyboardpartner-Shop für 10 Euro zzgl. Rücksendung ein Update bestellen.

Wir empfehlen bei Updates und Bugfixes, stets das ganze Repository neu downzuloaden; persönliche Einstellungen sind vor dem Überschreiben Ihres HOAX-Ordner zu sichern. Ein Komplett-Update besteht in der Regel aus zwei Datei-Gruppen. Die erste Gruppe besteht aus dem Steuerprogramm (Firmware) für den Mikrocontroller ATmega644P, der sich um die Abfrage der Bedienelemente kümmert. Die Firmware besteht aus den Dateien

• HOAX_main.hex (Flash-Inhalt) und
• HOAX_main.eep (EEPROM-Inhalt, z.B. Preset- und Parameter-Voreinstellungen).

Zum Update der Controller-Firmware verwendet man das Open-Source-Programm AVRdude oder eine ähnliche Lösung, die mit einem Arduino-kompatiblen Bootloader funktioniert. Und dann gibt es noch

• die FPGA-Konfigurationsdatei main_midi.bit, die im Prinzip das "Schaltbild" und das physikalische Modell der B3-Orgel enthält,
• die Datei hoax3rev.bin mit den Hallprogrammen für den kleinen Hall-DSP SPIN FV-1 und
• max. acht Scan-Cores HX_xxx.dat, die wiederum im FPGA selbst von einer Art "Mini-Prozessor" ausgeführt werden und die Abfrage der Tastatur (bzw. MIDI) bewerkstelligen.

Die letztgenannten drei Teile lassen sich relativ einfach per XMODEM-Protokoll und einem Makro-fähgen Terminal-Programm hochladen, der ATmega644P kümmert sich dann weiter darum. In der Regel sollten Sie bei jedem Update alle Teile auf die HX3-Platine laden, zuerst immer das Firmware-Update. Im folgenden haben wir die Vorgehensweise anhand der kostenlosen Tools AVRdude und Teraterm 4.7x beschrieben.

Der Update-Prozess setzt eine funktionierende Platine mit Bootloader voraus, der auf jeder Bausatz-Platine bereits vorhanden ist. Vorbereitung des USB-Kabels und Download der Firmware/Dokumentation wie unter Inbetriebnahme der Bausatz-Platine beschrieben. Das Upgrade/Update verlangt gewisse Kenntnisse im Umgang mit Kommandozeilen-Tools.

FTDI Kabel an HOAX-Platine angeschlossen, Reset-Jumper gesteckt für Firmware-Update über Bootloader

Update der Controller-Firmware per Bootloader

Der AVR-Controller ATmega644 kümmert sich auf der HOAX-Platine um die Abfrage der Bedienelemente und die Auswertung der empfangenen MIDI-Controllernummern. Bei kleineren Änderungen der Firmware sollte keine EEPROM-Programmierung erforderlich sein; Sie müssen dann nur hoaxflash.bat ausführen. hoaxflasheeprom.bat dagegen beschreibt auch das EEPROM neu. VCP-Treiber für FTDI-Kabel und ggf. Terminal-Programm TeraTerm 4.7x müssen installiert sein (siehe Inbetriebnahme der Bausatz-Platine). Das benötigte Flash-Tool AVRdude ist im HOAX-Ordner bereits vorhanden, es sollte von den Batch-Dateien aufgerufen werden (außer, Sie wissen, was Sie tun!). Der COM-Port muss für AVRdude zugänglich sein, d.h. TeraTerm ggf. vorher beenden.

Achtung: Das Programmieren des Controller-EEPROMs überschreibt alle nachträglichen Einstellungen und eigene Presets, ebenso wie die Seriennummer-Freischaltcodes, die dann neu eingegeben werden müssen.

• Ggf. aktuelles "HOAX_main.hex" und "HOAX_main.eep" aus unserem GIT-Repository downloaden (als Raw-Text) und in das "C:\HOAX"-Verzeichnis kopieren. Wir empfehlen grundsätzlich, auch gleichzeitig die FPGA-Konfiguration main.midi.bit und die Scan-Cores HX_xxx.dat neu herunterzuladen (zum Upload in HX3 siehe unten). Bei umfangreicheren Updates passen sonst möglicherweise Firmware und FPGA-Konfiguration nicht zusammen!
• Alternativ (und sicherer, Sie haben dann immer die neueste Dokumentation): Komplettes git-Repository als ZIP downloaden, entpacken und unter Beibehaltung der Verzeichnisstruktur in HOAX-Ordner kopieren; dann sind auf jeden Fall die COM-Partameter in den Batch- und Makro-Dateien erneut anzupassen (evt. Backup Ihrer Einstellungen aufbewahren)
• Platine mit Strom versorgen (5V/500mA)
• JP7 und JP8 müssen gesteckt sein
• JP5 setzen
• Windows "Command Prompt" im Verzeichnis "C:\HOAX" aufrufen, hoaxflash XX (oder hoaxflasheeprom XX für Neuprogrammierung auch des EEPROMs) eintippen, aber Befehl noch nicht mit ENTER abschicken. XX steht für die Schnittstellennummer, z.B. 14 für COM14.
• Weiteren Jumper auf Position R quer auf PL1 setzen, das sind die beiden mittleren Pins 5 und 6 genau in der Mitte (grüner Jumper im Bild)
• FTDI-Kabel an HOAX-Platine anschließen; GND = Pin1 = schwarzes Kabel!
• Jumper auf Position R abziehen, LED1 muss 5x aufblitzen. Möglichst während die LED noch blinkt, in Windows Command Prompt "hoaxflash.bat" aufrufen, d.h. jetzt die ENTER-Taste drücken
• AVRdude programmiert Controller mit HEX- und ggf. EEP-Datei seriell und führt Verifikation der Daten durch
• Falls "out of sync" oder "verification error", Vorgang wiederholen

Update der FPGA-Konfiguration (HX3-Sound-Engine)

Das FPGA ist der eigentliche Klangerzeuger und -verarbeiter der HX3-Platine; zusätzlich enthält es noch einen Mini-Controller für die Tastaturplatinen, der die eingestellte Scan-Routine abarbeitet. Beim Update der FPGA-Konfiguration sowie der Scan-Cores und Hallprogramme bleiben eigene Presets und Einstellungen sowie die Lizenz-Freischaltungen bestehen.

• JP7 und JP8 müssen gesteckt sein
• Ggf. aktuelle "main_midi.bit", "HX_*.dat" und "hoax3rev.bin" in Unterverzeichnis "FPGACORES" kopieren
• In der Makro-Datei "HOAX_UPLOAD.TTL" in "\TERATERM_MACRO" Pfade "mypath=..." kontrollieren (mehrfach vorhanden, mit Texeditor zu öffnen) und ggf. auf aktuellen Pfad zu "<drive>:\HOAX\FPGACORES" setzen (Default C:\HOAX\FPGACORES)
• TeraTerm starten und serielle Verbindung (57600/8n1) mit HX3-Platine herstellen, muss ENTER mit "#0:255=0 [OK]" beantworten
• Makro "HOAX_UPLOAD.TTL" mit "Control/Macro..." öffnen/ausführen, Anweisungen folgen
• Frage "Upload FPGA configuration?" mit Ja beantworten
• Bei Frage nach Scan Core folgende Ziffern eingeben:
  • Core 0 = Chained OrganScan61 (alt, von Projekt Klangcomputer), mit ein bis drei Platinen in Reihe an PL14
  • Core 1 = MIDI receive only
  • Core 2 = ScanFatar2 mit ein oder zwei Manualen an PL14, ggf. zusätzlich Bass-Scanplatine mit 4014-SR an PL15
  • Core 3 = Scan4014-Strip/Bass parallel 2x 44 Tasten, 2x 3 Platinen an PL15
  • Core 4 = Scan4014-Strip/Bass parallel 2x 49 Tasten, 2x 3 Platinen an PL15
  • Core 5 = Scan4014-Strip/Bass parallel 2x 61 Tasten, 2x 4 Platinen oder ein bis drei Scan4014-Inline parallel an PL15
  • Core 6 = Test-Routine (Auslieferungszustand)
  • Core 7 = OptoScan von B.A.S.S. an PL14
• Bei nicht vollständig bestückter Platine (R-Netzwerke fehlen) immer Core 6 (Testroutine) wählen, HOAX ist sonst evt. nicht mehr ansprechbar!
• Damit AVRdude wieder auf das FTDI-Kabel zugreifen kann, muss TeraTerm beendet oder Verbindung mit ALT-I unterbrochen werden!

Aufspielen der EEPROM-Patches

Auch unabhängig von Firmware- und FPGA-Updates veröffentlichen wir neue EEPROM-Parametersätze bei kleineren Änderungen als Patches, genauer gesagt als TeraTerm-Macro PATCH_MACRO.ttl in unserem GIT-Repository. Das Macro (Textdatei, Erstellungsdatum siehe dritte Zeile) aktualisiert die im HOAX-Controller-EEPROM abgelegten Parameter automatisch, ohne die Presets oder die eingestellte Scan-Routine zu verändern; es ist lediglich die serielle Verbindung zum HOAX/HX3 mit dem FTDI-Kabel und das Terminal-Programm TeraTerm notwendig. Auf diese Weise können Sie eine Neuprogrammierung des EEPROMs über AVRdude vermeiden.

• TeraTerm starten und serielle Verbindung (57600/8n1) mit HX3-Platine herstellen, muss ENTER mit "#0:255=0 [OK]" beantworten
• Makro "PATCH_MACRO.ttl" mit "Control/Macro..." öffnen/ausführen, ggf. Anweisungen folgen

Wichtig: Die Patch-Makro-Versionsnummer darf von der Firmware-Versionsnummer nur in der "Hundertstel"-Stelle abweichen (z.B. Patch-Macro 3.11, Firmware 3.10), ansonsten darf das Patch-Makro nicht angewendet werden!

Major Releases

Updates ab der 1. Versions-Nachkommastelle (z.B. von 3.11 auf 3.20) benötigen komplette Neuprogrammierung des ATmega644 mit FLASH und EEPROM sowie Hochladen der beigefügten FPGA-Konfiguration. Da vorherige Einstellungen im EEPROM überschrieben werden, müssen Sie ggf. auch Ihre Lizenznummern erneut eingeben und die Presets neu abspeichern.

Dateien im HOAX-Ordner

Firmware für Controller ATmega644:
HOAX_main.hex           Flash-Datei zum Upload per AVRdude, Default
HOAX_main_novibknob.hex Flash-Datei zum Upload per AVRdude, 4 Vibrato-Taster anstelle Common Presets
HOAX_main_latching.hex  Flash-Datei zum Upload per AVRdude, Latching Presets (einrastende Tasten)
HOAX_boot_main.hex      Flash-Datei komplett mit Bootloader, für 
                        OEM-Programmierung über ISP-Programmer
HOAX_main.eep           EEPROM-Datei zum Upload mit AVRdude oder Programmierung über ISP

FPGA-Konfigurationen in FPGACORES:
main_midi.bit           FPGA-Konfiguration zum Upload mit TeraTerm-Makro
*.dat                   Scan Core (PicoBlaze Keyscan-Routinen), zum Upload mit TeraTerm-Makro
*.bin                   SPIN-1 externe I2C Rerverb Programme, zum Upload mit TeraTerm-Makro

Batch-Dateien:
hoaxflash.bat           ruft AVRdude mit allen Parametern zum Flashen des 
                        Controllers mit "HOAX_main.hex" auf.
                        Parameter COM-Schnittstellennummer, z.B. "C:\HOAX>hoaxflash 14" for COM14
hoaxflasheeprom.bat     wie vor, jedoch zusätzlich mit EEPROM-Datei "HOAX_main.eep"

Sonstige:
avrdude.exe             AVRdude-Programm zum Firmware-Update über serielle Schnittstelle
libusb0.dll             Wird von manchen Windows-Systemen benötigt, um AVRdude auszuführen
ATmegaBOOT_xx8.c        Nur für Neukompilierung des Bootloaders mit WinAVR nötig
Makefile                Nur für Neukompilierung des Bootloaders mit WinAVR nötig

Verzeichnisse:
BETA                    enthält allerletzte Firmware und FPGA-Konfiguration
DOCS_PDF                Syntax-Tabelle zur Kommunikation und weitere Unterlagen
FPGACORES               FPGA-Konfiguration, Hallprogramme und Scan-Cores
PLATINEN                Schaltpläne, Bestückungspläne und weitere Unterlagen
TERATERM_MACRO          Update-Makros für Terminal-Programm TeraTerm
giveio                  Wird benötigt, um AVRdude auszuführen

Important

Major releases need complete programming of ATmega644 FLASH and EEPROM, also reload of FPGA configuration and re-entry of licence numbers.

Variants: 
HOAX_main.hex           Flash file for serial upload via AVRdude, default (non-latching preset buttons)
HOAX_main_novibknob.hex Flash file for serial upload via AVRdude, 4 vib/chorus buttons instead of 4 common presets
HOAX_main_latching.hex  Flash file for serial upload via AVRdude, latching preset keys
HOAX_boot_main.hex      Flash file complete with Bootloader, for OEM programming by ISP programmer
HOAX_main.eep           EEPROM file for upload via AVRdude or ISP programming

main_midi.bit           FPGA configuration, to be copied in directory FPGACORES, for upload by TeraTerm macro
*.dat                   Scan Core (PicoBlaze keyscan routines), for upload by TeraTerm macro
*.bin                   SPIN-1 externe I2C Rerverb Programme, for upload by TeraTerm macro