Ignition Project

Set the Gateway Token

The module uses Java's System.getenv("WATERLY_DEVICE_TOKEN") and sends the value in the existing x-waterly-connect-token header. It reads the environment inherited by the JVM at startup; it does not provision, persist, or dynamically reload environment variables.

Windows Gateway Server

1. 1
   Sign in to the Gateway server as an administrator. Search for Edit the system environment variables, then open System Properties ▸ Advanced ▸ Environment Variables.
2. 2
   Under System variables, add or edit WATERLY_DEVICE_TOKEN. Paste the Waterly-provided value without extra quotes or spaces and save all dialogs. Use system variables, not user variables.
3. 3
   Open Services (services.msc) and restart the actual Ignition Gateway service. Its name may be customized. Restart the full Windows service, not only Designer or the project.
4. 4
   After the Gateway returns, run a Gateway event and verify the log and received submission.

A variable set only in Command Prompt or PowerShell does not configure the service. If the variable is still missing after a full service restart, ask the administrator to check system variables and the service configuration; a server reboot may be needed if the service launcher retains its old environment.

Linux Gateway Server

For a systemd installation, have the administrator create /etc/ignition-waterly/gateway.env outside the project and repository, owned by root with file permissions 600 and directory permissions 700. In an editor, replace this fictional value with the Waterly token:

WATERLY_DEVICE_TOKEN=REPLACE_WITH_WATERLY_PROVIDED_TOKEN

Find the service with systemctl list-unit-files '*[Ii]gnition*'. If it is Ignition-Gateway.service, run sudo systemctl edit Ignition-Gateway.service and add this override. Substitute your actual service name throughout:

[Service]
EnvironmentFile=/etc/ignition-waterly/gateway.env

Reload the service definition, restart, and verify a submission:

sudo systemctl daemon-reload
sudo systemctl restart Ignition-Gateway.service

A shell export or user profile alone does not configure a system service. For a non-systemd installation, set the variable in that service's startup environment and restart the entire service.

Containerized Gateway

Inject the variable when creating the Gateway container. For an existing Docker Compose service named gateway, add an env_file entry. Preserve its current image, ports, and persistent data volume; this is an addition to your deployment, not a complete Compose file:

services:
  gateway:
    env_file:
      - /secure/ignition/waterly.env

Create that file on the deployment host, restrict access to the deployment administrator, and keep it outside source control. Use the WATERLY_DEVICE_TOKEN=REPLACE_WITH_WATERLY_PROVIDED_TOKEN format above, replacing the fictional value locally. After setting or changing it, recreate the Gateway container using your actual service name:

docker compose up -d --force-recreate --no-deps gateway

A host .env file alone does not inject the token into the container. docker compose restart does not apply changed environment settings. Keep the Gateway's persistent data volume when recreating it, then verify a submission.

Add a Gateway Event

The helper is sendDataToWaterly(tags=None, send_now_time_all=False). A full-path string or a list of strings continues to work with source timestamps by default.

1. 1
   In Designer, open Project Browser ▸ Scripting ▸ Gateway Events.
2. 2
   Add a Scheduled (specific times) or Timer (fixed rate) event. Give it a descriptive name and configure the timing.
3. 3
   Paste one of the example scripts below into the Script tab, enable the event, and Save the project.

Choose Source or Execution Timestamps

By default, last_change_timestamp comes from the Ignition QualifiedValue.timestamp, converted from milliseconds to whole Unix seconds. Keep this default for process values where the last actual change matters.

Select Individual Tags

Mix full-path strings with dictionaries containing tag_name and optional send_now_time. An omitted or False setting keeps source time. Both opted-in aggregate tags below receive the same execution timestamp:

tags = [
    "[default]Process/TankLevel",
    {"tag_name": "[default]DailyTotals/DailyRuntime", "send_now_time": True},
    {"tag_name": "[default]DailyTotals/DailyStarts", "send_now_time": True},
    {"tag_name": "[default]Process/Pressure"},
]
waterly.sendDataToWaterly(tags)

Use this in a Timer event, or inside onScheduledEvent() for a Scheduled event. Replace these fictional paths with your full Ignition paths, including provider and folders. The helper reads that exact tag_name and sends it unchanged as the payload's name. No alias or separate path field is needed.

Use Execution Time for Every Tag

Set send_now_time_all=True for this invocation to override every individual setting, including an explicit False:

tags = [
    "[default]DailyTotals/DailyFlowTotal",
    {"tag_name": "[default]DailyTotals/DailyRuntime", "send_now_time": False},
]
waterly.sendDataToWaterly(tags, send_now_time_all=True)

After the blocking tag read and before processing values, the helper captures now = int(time.time()) once. It reuses that whole-second Unix timestamp for the payload's timestamp and every tag using execution time. A later invocation captures a new now. These options configure the connector; they are not additional API payload fields.

Automatically Included System Tags

The helper appends [System]Gateway/CurrentDateTime, [System]Gateway/Timezone, and [System]Gateway/UptimeSeconds. They keep source timestamps by default; send_now_time_all=True applies to them too.

In either mode, only good-quality tags are submitted, values remain strings, and caller-owned tag lists remain unchanged so events can reuse them.