Actions API

The Actions API is used to expose module functionality through ArmorLink.

Actions can be discovered by the ArmorLink App and triggered through Commands routed by the Gateway.

For the conceptual overview, see Actions.

Basic Example

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

This defines an Action that:

• Has the internal identifier toggleFaceplate
• Is displayed as Toggle Faceplate in the ArmorLink App
• Reacts to the Facemask / toggle Command
• Executes toggleFaceplate() when triggered

For more information about Commands, see Commands.

Accessing the Actions API

Actions are created through the module instance.

module.actions()

For more information about modules, see ArmorLinkModule.

add(...)

Creates a new Action.

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

The value passed to add(...) is the internal Action identifier.

The identifier should be unique within the module.

Example:

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

label(...)

Sets the user-visible label of the Action.

.label("Open Helmet")

This label is displayed in the ArmorLink App.

If an Action is shown to users, it should have a clear and readable label.

command(...)

Associates the Action with an incoming Command.

.command("Facemask", "open")

The command consists of:

• Entity
• Command

Example:

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

When the module receives a Command with the matching Entity and Command values, ArmorLink executes the Action.

onExecute(...)

Defines the callback that runs when the Action is triggered.

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

The callback contains your application-specific behavior.

Example:

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

info

onExecute(...) is where your module reacts to an ArmorLink Action.

Buttons, sensors and timers remain part of your regular application logic.

Actions and Application Logic

Actions are triggered by incoming Commands.

Local events such as button presses are normal firmware logic.

Example:

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

This button handler is not an Action.

It sends a Command that may trigger an Action on another module.

For more information, see Commands.

App Integration

Actions are automatically discovered by the ArmorLink App.

The App uses Action metadata to display available functionality to the user.

Example:

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

The ArmorLink App can display this Action as Toggle Eyes and execute it remotely.

Multiple Actions

A module can expose multiple Actions.

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();
    });

Each Action can listen for a different Command and execute different behavior.

Recommended Naming

Use clear internal identifiers and readable labels.

Example:

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

Recommended pattern:

Value	Purpose	Example
Action ID	Internal identifier	toggleFaceplate
Label	User-visible text	Toggle Faceplate
Entity	Logical target inside the module	Facemask
Command	Requested operation	toggle

Example: Gateway Button Command

A module can send a Command to the Gateway.

In this example, Chest is the name of the Gateway module.

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

The Gateway can expose an Action that reacts to this Command.

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

When the Command is received by the Gateway, the matching Action is executed locally.

Example: Broadcast Command

A module can broadcast a Command to all modules.

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

Any module that exposes a matching Action can react to this Broadcast Command.

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

Broadcast Commands are useful for global or synchronized behavior.

Example: Remote Module Command

A module can also send a Command to another module.

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

The Command is routed through the Gateway and delivered to the Helmet module.

The Helmet module can expose a matching Action.

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

For more information about routing, see Gateway.

Summary

The Actions API exposes module functionality through ArmorLink.

Common methods include:

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

Actions are discovered by the ArmorLink App and triggered by Commands.

The Action callback contains the module-specific behavior that should run when the Action is executed.