Actions API

Die Actions API wird verwendet, um Funktionalität eines Modules über ArmorLink bereitzustellen.

Actions können von der ArmorLink App erkannt und über Commands ausgelöst werden, die durch das Gateway geroutet werden.

Für den konzeptionellen Überblick siehe Actions.

Basisbeispiel

module.actions()
    .add("toggleFaceplate")
    .label("Toggle Faceplate")
    .command("Facemask", "toggle")
    .onExecute([]{
        toggleFaceplate();
    });

Dieses Beispiel definiert eine Action, die:

• Die interne Kennung toggleFaceplate besitzt
• In der ArmorLink App als Toggle Faceplate angezeigt wird
• Auf den Command Facemask / toggle reagiert
• toggleFaceplate() ausführt, wenn sie ausgelöst wird

Weitere Informationen findest du unter Commands.

Zugriff auf die Actions API

Actions werden über die Modulinstanz erstellt.

module.actions()

Weitere Informationen findest du unter ArmorLinkModule.

add(...)

Erstellt eine neue Action.

module.actions().add("openHelmet");

Der an add(...) übergebene Wert ist die interne Action-ID.

Die Kennung sollte innerhalb des Modules eindeutig sein.

Beispiel:

module.actions()
    .add("openHelmet")
    .label("Open Helmet");

label(...)

Legt die für Benutzer sichtbare Bezeichnung der Action fest.

.label("Open Helmet")

Dieses Label wird in der ArmorLink App angezeigt.

Wenn eine Action Benutzern präsentiert wird, sollte sie eine klare und verständliche Bezeichnung besitzen.

command(...)

Verknüpft die Action mit einem eingehenden Command.

.command("Facemask", "open")

Der Command besteht aus:

• Entity
• Command

Beispiel:

module.actions()
    .add("openHelmet")
    .label("Open Helmet")
    .command("Facemask", "open")
    .onExecute([]{
        openFaceplate();
    });

Wenn das Module einen Command mit passender Entity und passendem Command empfängt, führt ArmorLink die Action aus.

onExecute(...)

Definiert den Callback, der ausgeführt wird, wenn die Action ausgelöst wird.

.onExecute([]{
    openFaceplate();
})

Der Callback enthält dein anwendungsspezifisches Verhalten.

Beispiel:

module.actions()
    .add("playSound")
    .label("Play Sound")
    .command("Audio", "play")
    .onExecute([]{
        dfplayer.play(1);
    });

info

onExecute(...) ist die Stelle, an der dein Module auf eine ArmorLink Action reagiert.

Buttons, Sensoren und Timer bleiben Teil deiner normalen Anwendungslogik.

Actions und Anwendungslogik

Actions werden durch eingehende Commands ausgelöst.

Lokale Ereignisse wie Button-Klicks bleiben normale Firmware-Logik.

Beispiel:

void btn1_handleClick()
{
    ArmorLink.sendCommand(
        "Helmet",
        "Facemask",
        "toggle"
    );
}

Dieser Button-Handler ist keine Action.

Er sendet einen Command, der eine Action auf einem anderen Module auslösen kann.

Weitere Informationen findest du unter Commands.

App-Integration

Actions werden automatisch von der ArmorLink App erkannt.

Die App verwendet die Action-Metadaten, um verfügbare Funktionalität darzustellen.

Beispiel:

module.actions()
    .add("toggleEyes")
    .label("Toggle Eyes")
    .command("Eyes", "toggle")
    .onExecute([]{
        toggleEyes();
    });

Die ArmorLink App kann diese Action als Toggle Eyes anzeigen und remote ausführen.

Mehrere Actions

Ein Module kann mehrere Actions bereitstellen.

module.actions()
    .add("openHelmet")
    .label("Open Helmet")
    .command("Facemask", "open")
    .onExecute([]{
        openFaceplate();
    });

module.actions()
    .add("closeHelmet")
    .label("Close Helmet")
    .command("Facemask", "close")
    .onExecute([]{
        closeFaceplate();
    });

module.actions()
    .add("toggleEyes")
    .label("Toggle Eyes")
    .command("Eyes", "toggle")
    .onExecute([]{
        toggleEyes();
    });

Jede Action kann auf einen anderen Command reagieren und unterschiedliches Verhalten ausführen.

Empfohlene Benennung

Verwende klare interne Kennungen und verständliche Labels.

Beispiel:

module.actions()
    .add("rightBtn1SingleClick")
    .label("Right BTN1 Single Click")
    .command("BTN_R1", "SINGLE_CLICK")
    .onExecute([]{
        dfplayer.stop();
    });

Empfohlenes Muster:

Wert	Zweck	Beispiel
Action ID	Interne Kennung	toggleFaceplate
Label	Sichtbarer Text	Toggle Faceplate
Entity	Logisches Ziel innerhalb des Modules	Facemask
Command	Angeforderte Operation	toggle

Beispiel: Gateway Button Command

Ein Module kann einen Command an das Gateway senden.

In diesem Beispiel ist Chest der Name des Gateway-Modules.

ArmorLink.sendCommand(
    "Chest",
    "BTN_R1",
    "SINGLE_CLICK"
);

Das Gateway kann eine Action bereitstellen, die auf diesen Command reagiert.

chestModule.actions()
    .add("rightBtn1SingleClick")
    .label("Right BTN1 Single Click")
    .command("BTN_R1", "SINGLE_CLICK")
    .onExecute([]{
        dfplayer.stop();
    });

Wenn der Command beim Gateway eintrifft, wird die passende Action lokal ausgeführt.

Beispiel: Broadcast Command

Ein Module kann einen Command an alle Modules senden.

ArmorLink.broadcastCommand(
    "Flaps",
    "toggle"
);

Jedes Module mit einer passenden Action kann auf diesen Broadcast Command reagieren.

module.actions()
    .add("toggleFlaps")
    .label("Toggle Flaps")
    .command("Flaps", "toggle")
    .onExecute([]{
        toggleFlaps();
    });

Broadcast Commands eignen sich für globale oder synchronisierte Aktionen.

Beispiel: Remote Module Command

Ein Module kann auch einen Command an ein anderes Module senden.

ArmorLink.sendCommand(
    "Helmet",
    "Facemask",
    "toggle"
);

Der Command wird über das Gateway geroutet und an das Helmet Module zugestellt.

Das Helmet Module kann eine passende Action bereitstellen.

helmetModule.actions()
    .add("toggleFaceplate")
    .label("Toggle Faceplate")
    .command("Facemask", "toggle")
    .onExecute([]{
        toggleFaceplate();
    });

Weitere Informationen zum Routing findest du unter Gateway.

Zusammenfassung

Die Actions API stellt Modul-Funktionalität über ArmorLink bereit.

Häufig verwendete Methoden sind:

• add(...)
• label(...)
• command(...)
• onExecute(...)

Actions werden von der ArmorLink App erkannt und durch Commands ausgelöst.

Der Action-Callback enthält das modulspezifische Verhalten, das bei der Ausführung der Action ausgeführt werden soll.