App Upgrade

App Upgrade installiert eine neue Anwendung über die Luftschnittstelle auf Ihren Sensoren mit Sensative VSM: Square Tracker, Square Air, Square Impact, Square Presence, Puck und Prism.

Die Anwendung - die App - bestimmt, was ein Tracker misst, wie oft er meldet und was in seinen Meldungen steht. Sie besteht aus bis zu 64 kleinen Regeln, die der Tracker ausführt, und wird als .vso-Datei aus Ihrem Sensative-Anwendungsbuild geliefert. Das ist keine Geräte-Firmware: Funk und LoRa-Handhabung bleiben von einem Upgrade unberührt, und es ist kein Firmware-Image beteiligt. Es ändern sich nur die Regeln.

Bisher ließ sich die App nur ändern, indem man ein NFC-Telefon an jeden Tracker hielt. App Upgrade erledigt das aus der Ferne, über dasselbe LoRa-Netz, das die Geräte ohnehin nutzen, und für so viele Geräte auf einmal, wie Sie wollen.

Bevor Sie beginnen

App Upgrade ist nicht für alle freigeschaltet. Sehen Sie App Upgrade nicht im Hauptmenü, bitten Sie Ihren Yggio-Administrator, den Zugriff auf App Upgrade für Ihr Benutzerkonto zu aktivieren. Es ist eine Einstellung je Benutzer, muss also für jede Person einzeln aktiviert werden, und Sie müssen sich ab- und wieder anmelden, bevor der Eintrag erscheint. Administratoren vergeben ihn, indem sie das Benutzerattribut app_upgrade_active in Keycloak, dem von Yggio genutzten Anmeldedienst, auf true setzen.

Außerdem brauchen Sie:

• Schreibzugriff auf jedes Gerät, das Sie aktualisieren wollen. Geräte, die Sie nur ansehen dürfen, werden abgewiesen.
• Geräte, die Sensative VSM LoRa-Tracker sind. Andere Gerätemodelle führen keine Regelanwendung aus.
• Geräte, die über einen ChirpStack-Netzwerkserver angebunden sind. Yggio kann kein Upgrade über Netmore, Actility Thingpark oder The Things Network ausführen, Geräte dort werden mit einem Hinweis in der Zeile übersprungen.
• Eine .vso-Datei von höchstens 64 kB aus Ihrem Anwendungsbuild.

Was ein Upgrade mit einem Gerät macht

Ein Upgrade ist kein Patch. Yggio versetzt den Tracker zuerst in den Programmiermodus, was seinen Regelspeicher leert, sendet dann die Regeln einzeln und weist den Tracker schließlich an, sie zu speichern und neu zu starten. Zwei Folgen sollten Sie vorher kennen:

• Ein Gerät, dessen Upgrade nicht abschließt, hört auf zu melden. Sein Regelspeicher ist leer, es hat also keine Regeln auszuführen und sendet keine Messwerte. Es ist weiterhin im Netz, empfängt weiterhin Downlinks und kann erneut aktualisiert werden - es ist nicht verloren. Starten Sie ein neues Upgrade dafür, und es kommt mit der App zurück, die dieses Upgrade installiert. Bis dahin meldet es nichts außer der Prüfsumme seines Regelspeichers.
• Ein Upgrade zu starten verwirft die eingereihten LoRa-Downlinks des Geräts. Die Übertragung braucht eine leere Downlink-Warteschlange, Yggio leert sie also zuerst. Alles andere, was dort wartet - eine Änderung des Meldeintervalls, ein Konfigurationsbefehl - wird verworfen und muss nach dem Upgrade erneut gesendet werden. Legen Sie Ihre Konfigurationsänderungen also nach das Upgrade, nicht davor.

Installieren Sie deshalb eine neue App zuerst auf einem Tracker, warten Sie, bis er wieder Messwerte meldet, und aktualisieren Sie erst dann den Bestand.

Geräte, die bereits die Prüfsumme der gewählten App melden, werden standardmäßig übersprungen, ein erneutes Upgrade über einen großen Bestand berührt also nur die Geräte, die es brauchen. Haken Sie Reprogram devices that already run this app an, wenn sie trotzdem gelöscht und neu geladen werden sollen.

Eine App hochladen

Apps liegen in einer Bibliothek auf der Seite App upgrade. Laden Sie eine hoch, bevor Sie ein Upgrade damit starten.

1. Öffnen Sie App Upgrade im Hauptmenü.
2. Drücken Sie im Abschnitt Apps auf Choose .vso file und wählen Sie die Datei.
3. Ändern Sie optional den App name - voreingestellt ist der Dateiname - und ergänzen Sie eine Description, damit Ihre Kolleginnen und Kollegen Ihre Apps auseinanderhalten können.
4. Drücken Sie Upload. Yggio liest die Datei und nennt Ihnen, wie viele Regeln sie enthält und welche Zielprüfsumme sie hat.

Die Bibliothek listet zu jeder App:

Spalte	Bedeutung
App	Der Name, den Sie vergeben haben, die Beschreibung und welche Sensoren ihre Regeln brauchen
Rules	Wie viele Regeln die App enthält, von maximal 64
Target CRC	Die Prüfsumme, die ein Tracker meldet, sobald die App installiert ist. Sie ist die Identität der App - daran erkennt Yggio ein erfolgreiches Upgrade und ein bereits aktuelles Gerät
Size	Die Größe der hochgeladenen Datei
Uploaded	Wann sie hochgeladen wurde

Yggio prüft die Datei beim Hochladen, eine Datei, die einen Tracker in einem schlechten Zustand zurücklassen würde, wird also abgewiesen statt gesendet. Abgewiesen wird eine Datei, wenn sie keine .vso-Datei ist, größer als 64 kB ist, überhaupt keine Regeln enthält, eine Compilerfehlerzeile enthält, eine leere oder mehr als 32 Byte lange Regel hat, oder Regelnummern hat, die außerhalb des Bereichs liegen, sich wiederholen oder keine lückenlose Folge ab Regel 0 bilden. Die Meldung nennt die betreffende Zeile, sodass Sie die Datei korrigieren und erneut hochladen können.

Geräte-Firmware

Ältere Dots-Firmware hängt sich auf, wenn ein Tracker denselben Downlink zweimal empfängt, und ein aufgehängter Tracker braucht Zuwendung vor Ort. Neuere Firmware behebt das. Die Einstellung Device firmware sagt Yggio, mit welcher der beiden es spricht, und wird je Upgrade gesetzt.

Einstellung	Was Yggio tut
Older firmware (safe for all)	Sendet denselben Downlink nie zweimal innerhalb eines Upgrades. Verstummt ein Tracker, fragt Yggio einmal seine Prüfsumme ab und wartet dann; startet ein Tracker mitten in der Übertragung neu, gibt Yggio ihn auf, statt Regeln erneut zu senden, die er schon hatte. Ein neues Upgrade beginnt wieder beim Programmierbefehl, und genau das macht einen erneuten Versuch überhaupt möglich.
Firmware with the duplicate-downlink fix	Darf einen verstummten Tracker erneut fragen und einen neu gestarteten dort fortsetzen, wo er aufgehört hat. Weniger Upgrades brauchen einen zweiten Anlauf.

Older firmware ist die Voreinstellung und die sichere Wahl. Die neuere Einstellung für einen Tracker zu wählen, der nicht aktualisiert wurde, kann ihn aufhängen. Die ältere Einstellung für einen aktualisierten Tracker zu wählen kostet nichts außer gelegentlich einem zusätzlichen Upgrade.

So oder so wird eine Regel, von der die Prüfsumme des Trackers belegt, dass sie nie ankam, immer erneut gesendet - das ist der Tracker, der sie zum ersten Mal empfängt, keine Wiederholung.

Wie lange ein Upgrade dauert

Regeln werden als LoRa-Downlinks gesendet, und wie schnell das geht, bestimmt die Datenrate (DR) des Geräts, die widerspiegelt, wie gut seine Funkverbindung ist. Die Zahlen unten gelten für eine volle App mit 64 Regeln:

Datenrate	Übertragungszeit für 64 Regeln
DR0	Etwa 3 Stunden
DR1	Etwa 1 Stunde 45 Minuten
DR2	Etwa 50 Minuten
DR3	Etwa 25 Minuten
DR4	Etwa 15 Minuten
DR5	Etwa 10 Minuten

Das sind Untergrenzen. Eine App mit halb so vielen Regeln braucht ungefähr halb so lange, und zur Übertragung selbst kommt die Wartezeit, bis jeder Tracker das nächste Mal meldet: Ein Tracker empfängt Downlinks nur, wenn er sendet, ein Gerät, das einmal pro Stunde meldet, braucht also bis zu einer Stunde allein, um in den Programmiermodus zu gelangen. Wait for programming mode im Startformular legt fest, wie lange Yggio darauf wartet; rechnen Sie mindestens zwei Meldeintervalle.

Geräte auf DR0 - DR2 sind weit von einem Gateway entfernt. Sie kommen irgendwann ans Ziel, aber die Übertragung ist langsam. Devices at a time begrenzt, wie viele Geräte gleichzeitig programmiert werden, denn Geräte an demselben Gateway konkurrieren um dieselbe Luft; eine niedrigere Zahl ist langsamer, aber zuverlässiger.

Upgrades laufen im Hintergrund weiter. Sie können die Seite schließen, oder Ihren Laptop, und später zurückkommen.

Ein Upgrade starten

Upgrades werden von Ihren Geräten aus gestartet, nicht von der App-upgrade-Seite. Es gibt zwei Wege.

Mehrere Geräte auf einmal

1. Öffnen Sie Devices im Hauptmenü.
2. Haken Sie die zu aktualisierenden Geräte an.
3. Wählen Sie in der Leiste, die unten erscheint, unter Select action den Eintrag App upgrade.
4. Wählen Sie die zu installierende App und den LNS connector, zu dem die Geräte gehören. Lassen Sie den Rest unberührt, sofern Sie keinen Grund haben, ihn zu ändern:
   • Reprogram devices that already run this app - standardmäßig aus, aktuelle Geräte werden also übersprungen statt gelöscht und neu geladen.
   • Device firmware - lassen Sie das auf Older firmware (safe for all), sofern Sie nicht wissen, dass die Tracker aktualisiert wurden. Siehe unten.
   • Devices at a time - wie viele Geräte gleichzeitig programmiert werden.
   • Wait for programming mode (minutes) - wie lange ein Gerät brauchen darf, um den Befehl aufzunehmen, der den Programmiermodus startet.
5. Drücken Sie Start upgrade.

Ein Upgrade umfasst höchstens 200 Geräte. Wählen Sie weniger und starten Sie mehrere Upgrades, wenn Sie mehr haben.

Ein einzelnes Gerät

Öffnen Sie das Gerät, gehen Sie zu LoRa control und verwenden Sie dort den Abschnitt App upgrade. Er zeigt, welche App das Gerät derzeit meldet, und die erwartete Übertragungszeit bei der Datenrate genau dieses Geräts.

Den Fortschritt verfolgen

Die Seite App upgrade listet Ihre Upgrades unter Upgrades auf, das neueste zuerst, mit dem Status jedes einzelnen und wie viele seiner Geräte fertig sind. Drücken Sie View in einer Zeile, um es zu öffnen.

Die Detailansicht nennt die App, ihre Zielprüfsumme und die Einstellungen, mit denen das Upgrade gestartet wurde, und zählt dann, wie viele Geräte fertig, übersprungen und in Arbeit sind. Darunter ist jedes Gerät mit seiner DevEUI aufgeführt, mit einem Status und einem Regelzähler wie 22 / 34. Klicken Sie auf eine Gerätezeile, um die Details Regel für Regel zu sehen: welche Regeln gesendet wurden, welche das Gerät bestätigt hat, wann, und wie viele Versuche jede gebraucht hat.

Die aufgeklappte Zeile zeigt außerdem die zuletzt vom Gerät gemeldete Prüfsumme, die Prüfsumme, die es vor dem Start des Upgrades ausführte, und die Zielprüfsumme. Eine Regel mit mehr als einem Versuch ist eine, die erneut gesendet wurde, nachdem das Gerät eine unveränderte Prüfsumme gemeldet hatte.

Ein Gerät wird nur an einer Sache als done markiert: Der Speicherbefehl hat die Downlink-Warteschlange ohne weitere zu sendende Nachrichten hinterlassen. Das belegt, dass das Netz den Speicherbefehl gesendet hat, nicht dass der Tracker zugehört hat. Jede done-Zeile zeigt daher bereits die Zielprüfsumme - das Gerät meldet sie, sobald die letzte Regel ankommt, noch bevor der Speicherbefehl überhaupt eingereiht ist - die Prüfsummen in der Zeile können Ihnen also nicht sagen, ob die App tatsächlich gespeichert wurde.

Um zu bestätigen, dass ein Upgrade angekommen ist, öffnen Sie das Gerät, gehen zu LoRa control und prüfen, ob die App, die es jetzt meldet, die von Ihnen installierte ist. Ein Tracker, der beim Senden des Speicherbefehls außerhalb der Abdeckung war, zeigt done und meldet trotzdem nichts; starten Sie ein weiteres Upgrade für ihn.

Gerätestatus:

Status	Bedeutung
pending	In der Warteschlange, noch nicht begonnen
flushing queue, awaiting queue drained	Die Downlink-Warteschlange des Geräts wird geleert, damit die Übertragung sauber beginnt
entering programming mode	Der Befehl ist eingereiht; es wird gewartet, bis das Gerät ihn bei seiner nächsten Meldung aufnimmt
awaiting empty rule memory	Es wird auf die Bestätigung gewartet, dass der Regelspeicher leer ist, was belegt, dass das Gerät im Programmiermodus ist
sending rules	Übertragung läuft; das Gerät bestätigt Regeln, sobald sie ankommen
resending lost rules	Eine Regel kam nicht an. Yggio hat aus der vom Gerät gemeldeten Prüfsumme ermittelt, welche, und sie erneut gesendet
saving and restarting	Alle Regeln sind vorhanden; dem Gerät wurde gesagt, es solle sie speichern und neu starten
done	Der Speicherbefehl hat die Downlink-Warteschlange des Geräts ohne weitere zu sendende Nachrichten hinterlassen. Bestätigen Sie die App unter LoRa control; die Prüfsummen in der Zeile können Ihnen nicht sagen, ob gespeichert wurde
skipped	Es wurde nichts gesendet: Das Gerät führt diese App bereits aus, oder es ist in einem Netz, über das Yggio nicht aktualisieren kann - die Zeile sagt, welcher Fall vorliegt
failed	Aufgegeben; siehe den Fehler in der Zeile

Ein Upgrade ist naturgemäß langsam. Ein Tracker bestätigt Regeln nur, wenn er meldet, ein Gerät, das mehrere Minuten beim selben Regelzähler steht, ist also normal und kein Fehler. Ein schlafendes Gerät oder eines außerhalb der Abdeckung hält nur seine eigene Übertragung auf, ohne die anderen zu beeinträchtigen.

Das Upgrade selbst ist running, während Geräte programmiert werden, und completed, failed oder cancelled, sobald sich jedes Gerät beruhigt hat.

Ein Upgrade stoppen und aufräumen

Drücken Sie Cancel upgrade auf der eigenen Seite eines Upgrades, um es zu stoppen. Yggio hört auf, Regeln zu senden, und leert die Downlink-Warteschlange jedes Geräts, dessen Programmierung begonnen hatte. Geräte, die noch auf ihren Zug warteten, behalten alle Downlinks, die andere Teile von Yggio für sie eingereiht hatten.

Abbrechen setzt ein Gerät nicht zurück. Ein Gerät mitten in der Übertragung hat einen leeren Regelspeicher und hört auf zu melden, bis ein Upgrade gelingt, genau wie oben beschrieben; starten Sie ein neues Upgrade dafür, wenn Sie so weit sind. Ein neues Upgrade beginnt immer bei der ersten Regel.

Ein Upgrade zu entfernen löscht nur seinen Fortschrittsdatensatz. Haken Sie auf der App-upgrade-Seite die nicht mehr benötigten Upgrades an und drücken Sie Remove selected, oder drücken Sie Remove all, um die ganze Liste zu leeren; Sie können das Upgrade, das Sie gerade ansehen, auch von seiner eigenen Seite aus entfernen. Die Liste behält jedes Upgrade, bis Sie es entfernen, es lohnt sich also, ab und zu aufzuräumen.

Nur ein abgeschlossenes Upgrade lässt sich entfernen. Ein noch laufendes Upgrade hat kein Remove auf seiner Seite, kann in der Liste nicht angehakt werden und bleibt bei Remove all außen vor - sein Datensatz ist das, woraus Yggio die Übertragung steuert, es zu entfernen würde die gerade programmierten Geräte also ohne jemanden zurücklassen, der ihnen den Rest ihrer Regeln sendet, und ohne jemanden, der das bereits Eingereihte aufräumt. Brechen Sie es zuerst ab, dann entfernen Sie es.

Eine App zu löschen entfernt sie nur aus der Bibliothek - Geräte, die sie bereits ausführen, führen sie weiter aus. Eine App, die ein unabgeschlossenes Upgrade noch verwendet, lässt sich nicht löschen; brechen Sie dieses Upgrade zuerst ab, die Meldung nennt es.

Wenn etwas nicht funktioniert

Was Sie sehen	Was es bedeutet
Kein App Upgrade im Menü	Der Zugriff ist für Ihr Konto nicht aktiviert, oder Sie haben sich seither nicht ab- und wieder angemeldet. Fragen Sie Ihren Yggio-Administrator.
"App upgrade is not enabled for your account"	Dasselbe wie oben.
Die Datei wird beim Hochladen abgewiesen	Die Datei ist keine gültige .vso-App - siehe die Gründe oben. Die Meldung nennt die fehlerhafte Zeile. Korrigieren Sie die Datei und laden Sie sie erneut hoch.
Ein Gerät wird beim Start des Upgrades abgewiesen	Sie haben nur Lesezugriff darauf, oder es läuft bereits ein Upgrade oder eine Almanach-Sendung dafür.
Kein Abschnitt App upgrade auf einer Geräteseite	Dieses Gerät ist kein Sensative VSM LoRa-Tracker, oder es ist nicht über einen ChirpStack-Netzwerkserver angebunden.
Ein Gerät ist skipped	Es meldet bereits die Prüfsumme dieser App, oder es ist in einem Netz, über das Yggio nicht aktualisieren kann. Um dieselbe App trotzdem neu zu installieren, starten Sie erneut mit Reprogram devices that already run this app.
Jedes Gerät steht auf pending	Das Upgrade hat nicht begonnen, oder der Connector erreicht den Netzbetreiber nicht. Wenden Sie sich an den Support, wenn sich nichts bewegt.
Ein Gerät bleibt bei entering programming mode	Es hat seit dem Einreihen des Befehls nicht gemeldet. Tracker empfangen Downlinks nur, wenn sie melden, geben Sie ihm also mindestens zwei Meldeintervalle, bevor Sie sich sorgen.
Ein Gerät ist failed	Es hat während der Übertragung aufgehört zu antworten, meist wegen schlechter Abdeckung oder weil es offline ist. Sein Regelspeicher ist leer, es meldet also keine Messwerte, bis ein Upgrade gelingt - starten Sie ein neues Upgrade dafür.
Eine App lässt sich nicht löschen	Ein unabgeschlossenes Upgrade verwendet sie noch. Brechen Sie dieses Upgrade ab, entfernen Sie es und löschen Sie dann die App.
Ein Upgrade lässt sich nicht entfernen	Es läuft noch. Brechen Sie es zuerst ab; ein abgebrochenes Upgrade lässt sich entfernen.