Applets ​

Overview ​

In Argonaut, an Applet is a user created automation. These general purpose automations allow you to define custom behavior and execution logic, and typically include a custom user interface to interact with.

Example use cases:

• showing information to an operator about what part is in station, and show relevant work instructions dynamically
• executing processes and performing data collection
• customized interface for creating materials
• automation of torque tools and other hardware
• PLC tag read / write with conditional behavior
• visualizing data from hardware in real time
• display station, AGV, hardware status, BOMs, and takt / cycle timers

There are four primary components involved with the configuration and execution of an Applet:

• Design - Specifies how an Applet looks and behaves
• Runner - A service that executes Applet Designs / Creates a running instance of an Applet Design (aka Applet Runtime).
• Client - A UI provided by the Applet Runner for interacting with a running Applet.
• Deployment - A configuration that assigns one or more Applet Designs to an Applet Runner

Applet Design ​

List ​

You can access the list of Applet Designs from the Argonaut Web Console's navigation sidebar, under Applets > Designs. This is also where you go to create a new Applet Design.

1. Add new applet design - click this to start a new Applet Design, navigating to the Applet Designer page
2. Version Number
   • Each Applet Design has a version. Every time you Fork an Applet Design it will effectively create a copy of the Design with the same name, but increment the version number. This allows you to be more strategic with how Designs are modified and deployed over time.
3. Notes - Additional information about the Design version.
4. Enabled - Whether or not this Design can be used in a Deployment. By default, this list view will filter out disabled Designs. (This column is normally hidden, you can enable it from the column settings in any of the header cells)
5. Actions
   1. Edit / View - Opens the Applet Design for editing / viewing, depending on the status of the Design.
   2. Activate and Lock - Changes the status of a Design from "staged" to "approved", which allows the Design to be used in a Deployment and prevents further edits. See Activating an Applet Design for more details
   3. Fork - Creates a new "staged" version of a Design, which essentially is just a copy of the Design with the same name, but incremented version number. You should fork a Design when you want to replace/modify a Design that is view-only.
   4. Copy - Creates a full copy of a Design with a distinct editing history.
   5. Archive - Disables a Design and prevent it from being used in a Deployment. Use this when you Fork a new version and activate it.

Migration of Applet Designs from older versions of Argonaut ​

Sometimes when a new version of Argonaut is deployed, there will be changes to how Applet Designs are structured internally. These changes may add, remove, or enhance functionality of Applet Designs. Usually these changes can be applied automatically, but sometimes they require some user interaction. When attempting to open a Design created with an older version of Argonaut, you might be presented with a Migration Dialog. This dialog will present all the changes that the user needs to acknowledge before proceeding to the editor. Once these changes are accepted, a new version will be saved. You can proceed to the editor without applying the changes, but this is not recommended as it might cause unexpected behavior or error messages to appear.

Anatomy of an Applet Design ​

There are two main things that go into making an Applet Design:

• Screens and Cells - these define how an Applet looks and interacts with an operator / user
• Variables and Variable Providers - these define the "data" or internal state for the Applet, but also allow the Applet to interact with other hardware and systems.

Screens and Cells ​

Most Applets typically have only one screen, but they can be configured with more for additional modes of operation. When an Applet is running, only one screen can be active at a time, and it fills the entire view on the device. Screens consist of one or more UI components called Cells.

Cells do different things depending on their type, and can even contain other cells to create a fully customizable layout. The Cells immediately under a Screen are displayed in a column. Other layout cell types (Row and Column) can be added to create complex layouts.

Base Cell Attributes ​

The configurable parts of a cell are called its "attributes". Most of a cell's attributes are specific to its type, but some attributes are common to all cell types. These are called the Base Cell Attributes, and include controls for:

• The background color for a cell, which can be specified by a color picker, or hexadecimal RGBA color code.

• Margin and Padding, which can be specified on a range of 0-16 and corresponds to a range of 0px-64px

• Weight - When cells are placed within a row or column, they are sized relatively to each other, to give a consistent layout regardless of display size/resolution. The weight of a cell controls the proportion of screen real-estate given to this cell, VS all of its sibling Cells. By default, every new cell has a weight of 1.

  

  In this example, the top text cell with a weight of 2 takes up twice the space in the Row cell than the text cell with a weight of 1, because their weight ratio is 2:1.

  The text cell below the row cell has a weight of 0, which means it only tries to take the minimum space it needs. The Row cell takes up the remaining vertical space because it has a weight of 1.

  NOTE

  Not all cells support having a weight of 0!

• Elevated - Whether to apply a drop shadow look.

Cell Modifiers ​

Most Cell attributes are statically configured and are not dynamic. However, depending on the cell type, certain attributes can be determined by the value in a variable instead, overriding the statically configured value.

Variables and Variable Providers ​

Variable providers can be used to:

• pull in data from external systems, for example to use as cell modifiers or in other variable providers
• transform the data, and derive new variables from other variables
• push the data out to external systems, for example to communicate operator actions

In this diagram, every block represents a Variable Provider, and each arrow line represents a variable.

If needed, variable providers can be re-ordered. However this might mess with references to other variables if the inputs and outputs are no longer "linear".

Variables can hold either a numeric value, and text value, or be empty. Additionally, each variable has a "status" that represents the usability of the variable. The status can be either "ok", "pending", or "errored".

Variable statuses propagate to other dependent variables. So if variable x has a pending status, and variable y is derived from x, it will also have a pending status. Variables without an ok status are not used in Cell Attribute Modifiers, and the default value is used instead.

Designer ​

This is the view you see when you open or start and new Design

There are two sections to the designer:

• Main - Contains the configuration interface for the item currently selected in the Overview
  • There are several tabs available in the main section:
    • General - Shows settings for the Design as a whole
    • Variables - Shows the settings for the currently selected variable provider
    • Screens - Shows the settings for the currently selected screen, or selected Cell within that screen
    • JSON - Shows the entire Design configuration as JSON. This is only really used for debugging, don't modify this directly unless you know what you're doing.
• Overview - Contains a treeview showing the overall structure of the Design. Clicking on an item in the overview will open that item's configuration interface in the Main editor.
  • Preview button - Opens a preview window so you can inspect how your Applet will look/behave
    • Applet Designs opened in the preview are locked in "Read Only mode" and cannot affect anything outside of the config
  • General - takes you to the General config settings in the Main editor.
  • Screens (draggable) - contains the list of Screens. Hovering over this presents an add button to add a new screen.
    • If you hover over a screen, an Add button will appear. Click this to add a new cell to the screen at the top level.
    • Under each screen you can see the list of cells it contains
    • Screens can be dragged to re-order them, which affects how they are shown in the Settings Sidebar in the runner.
    • Cells (draggable) - you can expand a screen to see the cells it contains.
      • If a cell can contain other cells, an Add button will appear if you hover over it in the Overview section.
  • Variables (draggable) - contains the list of Variable Providers and the Variables they Provide

Applet Runner ​

Before you can run any applets, you need to have at least one Applet Runner registered with your Argonaut context.

You can view the list of Runners from the Argonaut Web Console's navigation sidebar, under Applets > Runners. This view also lets you view and create Deployments, and inspect the running Designs each runner.

1. Runner ID - expand this to see the deployments assigned to the runner
2. Runner Status - indicates whether the Runner is connected to and communicating with the Argonaut API
3. New Deployment
4. Unregister Runner - this is disabled while there are Deployments assigned to the Runner
5. Deployment Name - expand this to see the applet designs
6. Edit Deployment - click this to open the Deployment Editor
7. Delete Deployment
8. Applet Runtime Status - indicates whether the Applet is running on the Runner. NOTE: this may report a false negative if the Runner is not reachable from the network your browser's machine is on.
9. Applet Inspection - opens the diagnostics / troubleshooting page for an Applet
10. Generate an registration code for adding a new Applet Runner

Creating an Applet Runner ​

Before you can run any applets, you need to have at least one Applet Runner registered with your Argonaut Context. Argonaut ships with a default Applet Runner which runs in the server cluster alongside the other Argonaut API Services. Depending on your needs, you might need to deploy additional Applet Runners.

You can add Runners to the server cluster alongside the other Argonaut services by modifying the helm chart configuration, or outside the cluster by deploying a docker container. Runners outside of the cluster are sometimes referred to as "Edge Runners".

applet:
    runners:
        other-runner: # <-- this will become the runner id
            mqttUser: ''
            mqttPassword: ''
            client:
                enable: true
                appInfo:
                updateMs: 180000
                extra: ''
            env:
                ARGONAUT_API_TLS: false # when in cluster, the argonaut API is accessed directly without going through the ingress, so this should be false

# Argonaut Applet Runner docker-compose
# Example useage:
#     export ARGOHOST=argo4-develop.rv-argonaut.com
#     export RELEASE=latest
#     export hostname=$(echo "$HOSTNAME" | tr '[:upper:]' '[:lower:]')
#     docker-compose -f runner1.yml up
version: '3.8'
services:
    applet-runner1:
        image: registry.gitlab.com/redviking/argonaut/v4/core/applet-runner:${RELEASE}
        volumes:
            - runner1:/home/node/app/packages/applet/runner/data
        ports:
            - 9081:80
        environment:
            - APPLET_RUNNER_ID=${hostname}-r1                                  # how the runner will appear in the Argonaut web console
            - PORT=80                                                          # must match port exposed in `ports`
            - ARGONAUT_API_HOST=${ARGOHOST}                                    # use hostname and optional port.
            - AUTH_LOGIN_URL=https://${ARGOHOST}/api/auth/provider/local/login # auth requests host.
            - GRAPHQL_API_ENDPOINT=https://${ARGOHOST}/hasura/v1/graphql       # Argonaut API host.
            - MQTT_URL=wss://${ARGOHOST}/mqtt                                  # MQTT Broker for system.
            - MQTT_USER=username                                               # MQTT User
            - MQTT_PASSWORD=password                                           # MQTT Pass
            - APPLET_CLIENT_HOST_ORIGIN=http://host-or-ip-of-runner            # Makes applet runner available from the argonaut web console
            - MQTT_EXTRA_OPTIONS={"rejectUnauthorized":false}                  # depends on how TLS is setup on Broker, you may need this option for self-signed/untrusted
volumes:
    runner1:

export ARGOHOST=argo4-develop.rv-argonaut.com
export RELEASE=latest
export hostname=$(echo "$HOSTNAME" | tr '[:upper:]' '[:lower:]')
docker-compose -f runner1.yml up

Registering an Applet Runner ​

Runners are added with a registration code, which you can get from the big "add" button on the runner list page.

Then, navigate to the Applet Client on the runner you want to add. This URL takes the format https://<your-argonaut-host-here>/applet/runner/<runner-id-here>/client

If this is a new runner that hasn't been registered before, you'll see a prompt for the registration code. Enter in the code from the Argonaut Web Console and the page will reload if everything is successful.

Once a Runner is registered, it will create a subscription to the Argonaut API, and automatically start running any Applets that are assigned to it.

Applet Runner configuration ​

All of the Runner configuration is controlled by environment variables. You can see the full list of supported options here.

For cluster runners, env can be configured globally through the applet.defaultEnv values, or per-runner with applet.runners.[runnerId].env

Applet Deployment ​

Applet Deployments assign Designs to Runners, and can provide additional configuration for designs.

Here are what each of the tabs offer:

• General
  • Set the name of the deployment, add notes, and select design versions to include in the deployment. You can modify the Runner field to "move" the deployment to a new Runner.
• Parameters
  • Some Applets can define extra inputs / configuration that is set by the Deployment. This is useful for reusing Applet Designs across multiple stations, where 90% of the Design is the same, but there's some variation from station to station. This is where you provide those values.
• Sparkplug
  • Applet Designs can expose their variables as Sparkplug Metrics to be consumed or modified by other hardware or other Applets. This tab offers a preview of the metrics that will be created for the Sparkplug Node on the runner. Each Linked design with exposed sparkplug metrics will have an associated Sparkplug Node.
• JSON
  • Copy/Edit the configuration as raw JSON. Only modify this if you know what you're doing!

The Runner associated with the Deployment will be updated as soon as the Deployment is saved.

Applet Client ​

Upon viewing, if not logged in yet, you will be presented with a login prompt:

Next, you will be prompted to select a Deployment. This choice will be remembered for the next time you visit this page. If only one Deployment is defined for a Runner, it will be automatically selected.

After the Deployment is selected, you will be connected to the first Applet Design linked in the deployment, and shown the first Screen of that Applet.

Sidebar ​

Additional controls for the Applet Client are available in a sidebar, which can be opened by clicking the gear in the top right corner

1. Toggles the sidebar
2. Manually opens the registration prompt
3. Disconnects from the currently Applet and logs the user out
4. Opens the Deployment Selection prompt
5. Linked Applet Design and version number
6. Screens for the Applet Design - Select one to view it
7. Triggers a reload - you may need to click this if you update the Deployment(s)
8. Inspect variables - View the value and state of each variable in the Applet
9. Opens an error viewer - This will become highlighted when a new error is encountered
10. Opens the API interface for the Applet Runner - useful for advanced troubleshooting

Applet Inspectior ​

On the Applet Runner / Deployment page,

Every Applet shown under a Deployment on the Applet Runner page has a "debug" button. Clicking this opens an Applet Inspector.

1. Filters the messages received to only be from specific sources
2. Toggles the visibility of "verbose" messages
3. Toggles automatically scrolling to the bottom of the message log
4. Pauses receiving logs
5. Clears the logs in the viewer
6. Variable Provider Type for an event logged
7. Event log description
8. Event details (expandable)
9. Event log
10. Variable provider type, and name (if specified)
11. Variable name
12. Variable status / error. If this is a custom/local provider, you can edit this field
13. Value for the variable
14. If the Variable is from a custom/local provider, click this to change the value.