Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- wizard:firmware-update-definition [2014/12/14 09:08] – [XML-Struktur einer Firmware-Update-Definition] Tilly
+++ wizard:firmware-update-definition [2023/12/04 21:14] (aktuell) – [Firmware-Repo] akuhtz
@@ Zeile 1: / Zeile 1: @@
 ====== XML-Struktur einer Firmware-Update-Definition ======
-<WRAP center round todo 60%>
-Ab BiDiB-Wizard-1.7
-</WRAP>
 Bei manchen BiDiB-Knoten reicht die bisherige Aufteilung in eine Firmware- und EEPROM-Datei (000- bzw. 001.hex) wegen der vielfältigen Konfigurationsmöglichkeiten dieses Knotens nicht mehr aus. Zusätzlich wird noch zwischen Installation und Update unterschieden.
-Aus diesem Grunde wurde für das fehlerfreie Aufspielen der Firmware auf einen BiDiB-Knoten eine Beschreibung erdacht. Mit ihrer Hilfe können Konfigurationsprogramme wie BiDiB-Monitor und BiDiB-Wizard passende Auswahlmenüs bereitstellen. Dadurch kann ein Anwender verschiedene Vorgänge, wie Neuinstallatuion oder Firmware-Update, komfortable und vor Allem verwechselungsfrei durchführen.
+Aus diesem Grunde wurde für das fehlerfreie Aufspielen der Firmware auf einen BiDiB-Knoten eine Beschreibung erdacht. Mit ihrer Hilfe können Konfigurationsprogramme wie BiDiB-Monitor und BiDiB-Wizard passende Auswahlmenüs bereitstellen. Dadurch kann ein Anwender verschiedene Vorgänge, wie Neuinstallation oder Firmware-Update, komfortable und vor Allem verwechslungsfrei durchführen.
-Das nachfolgende Beispiel zeigt die XML-Struktur welche vom Wizard ausgwertet werden kann. Das XML-File hat gemäss Konvention den Namen **firmware.xml** und wird im Zip-File neben den Hex-Files gespeichert.
+Das nachfolgende Beispiel zeigt die XML-Struktur welche vom Wizard ausgewertet werden kann. Das XML-File hat gemäss Konvention den Namen **firmware.xml** und wird im Zip-File neben den Hex-Files gespeichert.
 <code xml>
@@ Zeile 28: / Zeile 24: @@
 </code>
-Im <FirmwareDefinition>-Tag wird die Struktur der Firmware angegeben. Dabei werden unterschiedliche Node-Typen unterstützt:
+Im ''<FirmwareDefinition>''-Tag wird die Struktur der Firmware angegeben. Dabei werden unterschiedliche Node-Typen unterstützt:
-  * DeviceNode: Äusserer Node-Typ der die Firmware-Files eines Node zusammenfasst. Hier //können// VID und PID sowie ein Kommentar angegeben werden.
+  * DeviceNode: Äusserer Node-Typ der die Firmware-Files eines Node zusammenfasst. Hier sollten
+    * die Hersteller Id (''VID''),
+    * die erweiterte Hersteller Id (''EVID'') falls notwendig (z.B. ''258'' für //OpenDCC//),
+    * die Produkt Id (''PID'') sowie optional
+    * ein Kommentar angegeben werden.
   * FirmwareNode: Node-Typ der ein Firmware-File (hex) definiert. Hier muss die Destination des Hex-File, der Text sowie der Filename des HEX-File innerhalb des Archiv (Zip-File) angegeben werden.
   * SimpleNode: Dieser Node-Typ kann verwendet werden um eine oder mehrere zusätzliche Abstraktions-Ebenen zu definieren.
-Das nachfolgende Beispiel zeigt eine minimale Definition des <FirmwareDefinition>-Tag:
+Das nachfolgende Beispiel zeigt eine minimale Definition des ''<FirmwareDefinition>''-Tag:
 <code xml>
    <FirmwareDefinition>
-      <Node xsi:type="DeviceNode">
+      <Node xsi:type="DeviceNode" Comment="Kommentar" VID="13" EVID="258" PID="132">
          <Nodetext Lang="de-DE" Text="Beispiel Firmware"/>
          <Nodetext Lang="en-EN" Text="Sample Firmware"/>
@@ Zeile 47: / Zeile 47: @@
 </code>
-Mit dem Attribute "DestinationNumber" wird der Zielspeicherbereich auf dem Knoten festgelegt ( 0 = Flash, 1 = EEPROM.). Details dazu sind auf [[http://www.bidib.org/protokoll/bidib_fw_update.html#T443|bidib.org]] zu finden.\\
+Mit dem Attribute ''DestinationNumber'' wird der Zielspeicherbereich auf dem Knoten festgelegt ( 0 = Flash, 1 = EEPROM.). Details dazu sind auf [[http://www.bidib.org/protokoll/bidib_fw_update.html#T443|bidib.org]] zu finden.\\
 \\
-Es besteht auch die Möglichkeit eine CV-Defintions anzugeben, welche dann im //firmware.zip// mitgeliefert werden muss:
+===== CV-Definitionsdatei =====
+Es besteht auch die Möglichkeit eine CV-Definition anzugeben, welche dann im //firmware.zip// mitgeliefert werden muss:
 <code xml>
    <FirmwareDefinition>
-      <Node xsi:type="DeviceNode">
+      <Node xsi:type="DeviceNode" Comment="Kommentar" VID="13" EVID="258" PID="xyz">
          <Nodetext Lang="de-DE" Text="Beispiel Firmware"/>
          <Nodetext Lang="en-EN" Text="Sample Firmware"/>
@@ Zeile 59: / Zeile 62: @@
          </Node>
          ...
+         <CvFilename>BiDiBCV-13-xyz.xml</CvFilename>
       </Node>
-      <CvFilename>BiDiBCV-13-xyz.xml</CvFilename>
    </FirmwareDefinition>
 </code>
+Ab dem Wizard-1.9 können CV-Dateien direkt in den Wizard importiert werden, falls sie in der ''FirmwareDefinition'' hinterlegt sind.
-==== Darstellung im Wizard ====
+Ab dem Wizard-1.9.1 werden die CV-Dateien mit der Version versehen importiert. Das nachfolgende Beispiel würde die CV-Datei ''BiDiBCV-13-201-0.1.xml'' erzeugen:
+<code xml>
+   <Version Version="0.1" Lastupdate="20140411" Author="BiDiB.org" Pid="201" Vendor="013"
+      Description="Firmware Definition for StepControl !!!Minimum-Beispiel!!!"/>
+   <FirmwareDefinition>
+      <Node xsi:type="DeviceNode" Comment="Kommentar" VID="13" EVID="258" PID="201">
+         <Nodetext Lang="de-DE" Text="Beispiel Firmware"/>
+         <Nodetext Lang="en-EN" Text="Sample Firmware"/>
+         <Node xsi:type="FirmwareNode" DestinationNumber="0" >
+         ...
+         </Node>
+         ...
+         <CvFilename>BiDiBCV-13-201.xml</CvFilename>
+      </Node>
+   </FirmwareDefinition>
+</code>
+===== Default-Labels =====
+Die Default-Labels können im ''firmware.xml'' angegeben werden. Sie müssen an der letzten Stelle der Daten innerhalb der ''FirmwareDefinition'' eingefügt werden. Beim Laden des Firmware-Archiv erscheint dann im Wizard der Hinweis, ob die Default-Labels importiert werden sollen.
+<code xml>
+<Firmware ...>
+   ...
+   <FirmwareDefinition Version="2.06.00" Status="beta" ProtocolVersion="0.7" RequiredMinVersion="2.01.00" >
+      ...
+      <!-- other parts -->
+      <CvFilename>BiDiBCV-13-201.xml</CvFilename>
+      <DefaultLabels>
+         <DefaultLabelsFile Lang="de-DE" Filename="bidib-default-names-13-138-de.xml" />
+         <DefaultLabelsFile Lang="en-EN" Filename="bidib-default-names-13-138-en.xml" />
+      </DefaultLabels>
+   </FirmwareDefinition>
+</Firmware>
+</code>
+:!: Alle referenzierten Dateien wie die //DefaultLabelsFile//s müssen im Firmware-ZIP enthalten sein.
+===== Version, Status und Node-Images =====
+Ab dem Wizard-1.12.2 werden die ''<FirmwareDefinition>'' in den CV-Dateien mit den Attributen ''Version'' und ''Status'' versehen importiert. Wenn ''Version'' angegeben ist, wird auf das Parsen der Filenamen zur Ermittlung der Version verzichtet. //Optional// können noch die Protokollversion ''ProtocolVersion'' sowie die aktuelle minimal Version ''RequiredMinVersion'' angegeben werden.
+Folgende Werte sind als ''Status'' definiert:
+  * ''beta''
+  * ''stable''
+  * ''mandatory''
+Als weitere Änderung muss der ''CvFilename'' jetzt unter dem ''DeviceNode'' angegeben werden.
+Neu besteht auch die Möglichkeit ein Bild der Baugruppe im Firmware-ZIP mitzuliefern. Dazu muss das Element ''NodeImages'' wie im Beispiel unten unter dem ''DeviceNode'' angegeben werden.
+<code xml>
+   <Version Version="0.1" Lastupdate="20190920" Author="BiDiB.org" Pid="132" Vendor="013"
+      Description="Firmware Definition for IF-2"/>
+   <FirmwareDefinition Version="2.06.00" Status="beta" ProtocolVersion="0.7" RequiredMinVersion="2.01.00" >
+      <Node xsi:type="DeviceNode" Comment="BiDiB-IF2" VID="013" EVID="258" PID="132">
+         <Nodetext Lang="de-DE" Text="Beispiel Firmware"/>
+         <Nodetext Lang="en-EN" Text="Sample Firmware"/>
+         <Node xsi:type="FirmwareNode" DestinationNumber="0" >
+         ...
+         </Node>
+         ...
+         <!--
+         <CvFilename>BiDiBCV-13-132.xml</CvFilename>
+         <DefaultLabels>
+             <DefaultLabelsFile Lang="de-DE" Filename="bidib-default-names-13-138-de.xml" />
+             <DefaultLabelsFile Lang="en-EN" Filename="bidib-default-names-13-138-en.xml" />
+         </DefaultLabels>
+         -->
+         <NodeImages>
+             <Image>bidib-13-132.png</Image>
+         </NodeImages>
+      </Node>
+   </FirmwareDefinition>
+</code>
+:!: Alle referenzierten Dateien wie //NodeImage// oder //CV-Defintions-File// müssen im Firmware-ZIP enthalten sein.
+===== Update Only =====
+Um mit einem FW-Update nur die Firmware ohne Löschen der Einstellungen (Port-Konfiguration, Makros, etc.) zu aktualisieren, wird oft die "Update Only" Option angeboten.
+In einem solchen Fall wird das Attribut ''IsUpdate="true"'' verwendet, wodurch die Tools erkennen, dass es sich um eine "Update Only" Option handelt.
+<code xml>
+<Node xsi:type="DeviceNode" Comment="BiDiB-IF2 UPDATE" IsUpdate="true" VID="013" PID="132" EVID="258">
+</code>
+In diesem Fall prüfen die Tools, ob die gleiche ProduktID und Major-Version verwendet wird, bevor diese Option im Firmware-Update-Dialog angeboten wird.
+===== Changelog Informationen =====
+<code xml>
+<Firmware ...>
+   ...
+   <FirmwareDefinition Version="2.06.00" Status="beta" ProtocolVersion="0.7" RequiredMinVersion="2.01.00" >
+      ...
+      <!-- other parts -->
+      ...
+      <Changelog>changelog.json</Changelog>
+   </FirmwareDefinition>
+</Firmware>
+</code>
+:!: Die refenrenzierte json Datei muss Firmware-ZIP enthalten sein.
+Die json Datei muss dabei dem folgenden Schema entsprechen.
+<code json>
+{
+	"product": "",
+	"owner": "",
+	"versions": [
+		{
+			"version": "1.04.05",
+			"releaseDate": "20210630",
+			"changelog": [
+				{
+					"lang": "de",
+					"description": "..."
+				},
+				... weitere Übersetzungen
+			]
+		},
+		... weitere Versionen
+	]
+}
+</code>
+===== Darstellung im Wizard =====
 Nach der Auswahl des Zip-File wird die Struktur im Wizard analysiert und in einem Tree angezeigt. Der Benutzer kann anschliessend die Firmware-Pakete auswählen welche übertragen werden sollen.
@@ Zeile 90: / Zeile 225: @@
    <Version Version="0.1" Lastupdate="20140411" Author="BiDiB.org" Pid="201" Vendor="013"
       Description="Firmware Definition for StepControl !!!Minimum-Beispiel!!!"/>
-   <FirmwareDefinition>
+   <FirmwareDefinition Version="1.04.00" Status="stable" ProtocolVersion="0.7" RequiredMinVersion="1.01.00">
-      <Node xsi:type="DeviceNode" VID="013" PID="201" >
+      <Node xsi:type="DeviceNode" VID="013" EVID="258" PID="201" >
          <Nodetext Lang="de-DE" Text="StepControl: Komplette Installation"/>
          <Nodetext Lang="en-EN" Text="StepControl: complete installation"/>
@@ Zeile 124: / Zeile 259: @@
          </Node>
       </Node>
-      <Node xsi:type="DeviceNode" VID="013" PID="201" >
+      <Node xsi:type="DeviceNode" VID="013" EVID="258" PID="201" >
          <Nodetext Lang="de-DE" Text="StepControl: Update Installation"/>
          <Nodetext Lang="en-EN" Text="StepControl: update installation"/>
@@ Zeile 137: / Zeile 272: @@
 </code>
+==== Firmware-Repo ====
+Firmware-Pakete im ZIP-Format (mit firmware.xml) können im Firmware-Repo auf github comitted und gepushed werden. Nach einem neuen Commit läuft ein Job im Gitlab-Repository welches das Firmware-Paket scanned (auf Vorhandensein des firmware.xml) und die Meta-Daten (PID, VID, EVID, Version, Name, etc.) aus dem firmware.xml ausliest.
+Mit diesen Meta-Daten wird dann ein json-Dokument erzeugt, welches den aktuellen Stand im Firmware-Repo beinhaltet. Anschliessend wird das json-Dokument und alle geänderten Firmware-Pakete auf den ''bidib.org'' Server kopiert.
+Dieses json-Dokument ([[https://repository.bidib.org/repository.json|https://repository.bidib.org/repository.json]]) kann heruntergeladen werden und wird z.B. auch vom BiDiB-Monitor verwendet um die Firmware-Daten im Knoten-Firmware-Repository anzuzeigen.
+=== Neue Firmware hinzufügen ===
+Um ein neues Firmware-Paket hinzuzufügen, muss das Firmware-Paket im ZIP-Format in den entsprechenden Unterordner von ''repo'' kopiert werden.\\
+Die Unterordner sind anhand der ''VID'' bezeichnet, für OpenDCC also die ''13'', Tams ist ''62'', Fichtelbahn ist ''251''.
+Nach Commit und Push läuft der Job im Gitlab-Repo.
+=== Bestehende Firmware überschreiben ===
+Um ein bestehendes Firmware-Paket zu überschreiben kann man das neue Firmware-Paket einfach über das alte kopieren. Bei Merge-Konflikten einfach die Änderungen des neuen Firmware-Paket übernehmen.\\
+Es ist nicht notwendig das alte Firmware-Paket zuerst zu löschen.
+Nach Commit und Push läuft der Job im Gitlab-Repo.