Gateway Functionality Testing User Guide
Litmus Gateway Functionality Testing is a load and resource testing tool for a Litmus Edge (LE) gateway. It connects to your gateway, deploys test workloads, and lets you watch CPU and memory usage react live in a browser UI: no separate client to install, just a container.
Before you begin
Important: Run the container on a separate machine from the gateway under test, not on the gateway itself. Running it on the gateway competes with the gateway for CPU and memory, which skews the very results you're trying to measure.
Before you begin, make sure you have the following:
- LE installed on the gateway: download the LE ISO from the Litmus Central Portal and install it following the ISO Installation on an Industrial PC (IPC) guide.
- The docker-compose.yml file: download it from the Litmus Central Portal. It pins the tool version it shipped with, so if you also download the image tar file, take both from the same release.
- Docker Engine 20.10+ on Linux, or Docker Desktop 4.x+ with the Windows Subsystem for Linux 2 (WSL2) backend enabled on Windows.
- Docker Compose v2 (the docker compose command, from the docker-compose-plugin package on Linux).
- Host architecture: amd64/x86_64 (Intel/AMD).
- Network access:
- Access to litmusedge.azurecr.io to pull the images (first run and every update). The pull is anonymous; no registry sign-in needed. If the host has no access to the registry, download the image tar file from the Litmus Central Portal instead and load it with docker load -i <file>.tar.gz before running the container. That one file holds both images the tool needs.
- Outbound HTTPS from the host to the target LE gateway.
- Port 4007 free on the host for the UI. With the servers profile, ports 4222 (NATS) and 5432 (PostgreSQL) too.
- LE gateway credentials: a username/password (JWT login) or a bearer token for the gateway you want to test. Analytics import specifically requires LE 4.0+.
Running the container
This pulls the images from Azure Container Registry (ACR) and starts the app together with the bundled NATS and PostgreSQL servers the Integrations test publishes to. Once it's up:
- Open http://localhost:4007 in a browser.
- Or check curl http://localhost:4007/health for a quick readiness check.
Your gateway connection and any saved scenarios/templates persist on a volume, so they survive docker compose restart or a host reboot.
Leave off --profile servers if you don't plan to run the Integrations test. You still get the app and the OPC UA client, just without the NATS and PostgreSQL servers.
Pointing the gateway at the bundled servers
The LE gateway dials out to NATS and PostgreSQL, so they have to be reachable at your docker host's LAN IP, not localhost. Set GWT_SERVERS_HOST in a .env file next to docker-compose.yml:
Compose reads that file on every run, so both settings survive restarts and updates, and plain docker compose up -d starts the servers from then on. You can pass the variable inline instead:
but that applies only to that one command. The next docker compose up -d without it leaves the value empty, and the connectors publish nowhere.
With the host set, the Integrations card (and Auto test) default to the bundled servers. Postgres credentials default to litmus/litmus/litmus and can be overridden with GWT_PG_DB / GWT_PG_USER / GWT_PG_PASSWORD.
Connecting to your gateway
On first load, the UI shows a Connect to your gateway card:
- Enter the gateway's IP address or hostname in Gateway address (just the IP/hostname; https is assumed).
- Pick an auth method (Username / password, API token, or First login) and fill in the matching fields (for example, username and password).
- Leave Allow self-signed certificate checked if the gateway uses a self-signed cert.
- Press Connect.
Once connected, the header badge changes from NOT CONNECTED.
Running tests
Once connected, Home shows the gateway card (manufacturer, model, hardware version, edge software version, serial number, disk usage) and live CPU/memory usage tiles, followed by the Auto test panel and the individual Components test cards (DeviceHub, DataHub, Analytics, Integrations, Flows, OPC UA).
Auto test runs every currently unlocked test in sequence using whatever configuration is set on each component card, so set those first:
- Adjust the fields on the component cards you care about before running. For example, in DeviceHub, change Tags each (or Devices / Driver) from its default.
- Press Start auto test to run every unlocked test in sequence: each step runs its setup, settles 60s, observes 30s, and records the CPU/RAM change, ending with a final stabilization reading. Quick test skips the settle windows for a faster single-pass run.
Some cards only unlock after a prerequisite test runs. DataHub and OPC UA need a DeviceHub test first, and Analytics needs a saved Analytics export JSON from the Custom Analytics page.
Important: The OPC UA test changes the gateway's OPC UA server settings and does not change them back. To connect and verify tag subscriptions, it sets the server's security mode to None and its authentication mode to Anonymous, restarts the server, then leaves both on those values. It applies this every run, whatever the gateway had before, and Cleaner does not restore the previous settings. If the gateway you're testing has OPC UA security configured, note what it was set to first and put it back by hand afterwards.
Once started, a Baseline before test card captures the CPU/memory/device counts at the moment you pressed start, with Download snapshot / Export Word / Clear buttons. The Auto test card itself shows live per-step progress: each row moves through PENDING to RUNNING to DONE as the sequence proceeds, or SKIPPED with a reason (for example, Analytics skipped when no custom JSON is saved). While a step is RUNNING, it shows what it's doing (for example, "Deployed 10 device(s) / 1000 tag(s)") and counts down through Settling (60s) then Observing (30s). Once DONE, it shows what it did along with the before-to-after and peak CPU/RAM for that step (for example, "CPU 6% to 9% (+2.7, peak 9%)"). Once every step finishes, the Final result row fills in with the overall CPU/RAM change from baseline to after the stabilization reading. Wait for that to finish before exporting your report.
Submitting your report for self-certification
This tool is what lets you self-certify a gateway. Instead of shipping the physical gateway to Litmus for testing, you run the tests yourself and submit the resulting report for Litmus to review and approve.
- Run the tests that apply to your setup: the individual component tests, or Auto test to run the full sequence in one go.
- Once testing is complete, the Export Word button in the Baseline before test card on Home turns green. Press it to download the Word (.docx) report. It follows Litmus's official gateway test report template and is the version used for certification review. You can also press Download snapshot there to keep the HTML version for your own records.
- Complete the manual hardware checks below and record the results directly in the downloaded .docx report, editing it in Word. Leave the Litmus Approval History table blank. It sits below Document Revision History, and Litmus fills it in when the report is approved. You can use Document Revision History for your own edits.
Manual hardware checks
Check the following directly on the physical device and add the results to the report by hand.
The exported .docx marks the fields it can't fill in itself in red: Video Interfaces, USB Ports, Wi-Fi, Default Boot Mode, Default Secure Boot Setting, and Power Supply. Replace those with the results below.
- Check the factory BIOS settings.
- Note whether Boot Mode is set to Legacy or UEFI. LE requires UEFI.
- Note whether Secure Boot is set to enabled or disabled. LE requires it to be disabled.
- If the device has a Trusted Platform Module (TPM), note whether TPM is set to enabled or disabled, and the TPM module's name.
- Note the power supply options (such as 24V DC or 120V AC).
- Note the number and type of video interfaces (such as DP or HDMI).
- Test all USB ports with a keyboard device.
- Compare the Ethernet and serial port counts the app reports to the number of Ethernet and COM ports visible on the exterior of the device. If they don't match, check the BIOS to see whether all the ports are listed there.
If the gateway includes any of this optional hardware, check it too:
- Two or more COM ports: test COM2 and higher with an RS232/RS485 device such as a Modbus RTU server. You may need to check the BIOS setting for each COM port and select RS232 or RS422/485. COM1 is reserved for the gateway's Text User Interface (TUI), so it should not be tested with a device.
- Wi-Fi module: connect to a Wi-Fi network and confirm it associates successfully.
- Cellular modem: connect to a cellular network and confirm it registers successfully.
- CAN bus module (HMS Networks): wire it to another CAN device on the same bus (such as a CAN bus analyzer or a PLC) and confirm traffic passes both ways.
Once you've recorded the manual checks in the .docx, finish up:
- Email the completed report to [email protected]. Attach the .docx, send one gateway model per email, and use the subject line Gateway test report: <your company> - <gateway make and model>. In the body, include:
- Your name, company, and contact email.
- The gateway's make, model, and part number.
- The LE version you tested.
- Any tests you skipped, and why.
- Whether Litmus may list the gateway publicly on the partner-validated gateways page, and the exact make and model name to display there.
- Litmus confirms receipt by email. A member of the Litmus industrial team then reviews the report and follows up from their own email address, either to approve the gateway's certification or to ask about anything that needs another look. Once it's approved, and if you've agreed to a public listing, the gateway is added to the partner-validated gateways page and Litmus emails you to confirm.
Feature overview
- Connect: sign in to a gateway with LE credentials or a bearer token.
- Gateway card: friendly name, address, manufacturer, model, hardware version, edge software version, serial number, disk usage, and per-service versions.
- Live CPU and memory tiles: status meters and sparklines, polled every 3 seconds.
- Component tests: each with a baseline and live deltas.
- DeviceHub: deploys devices with polling tags using any driver on the gateway.
- DataHub: enables data storage on the test devices.
- Analytics: imports an Analytics export into a dedicated group.
- OPC UA: imports DeviceHub tags into the OPC UA server namespace, then sets the server to security mode None with Anonymous authentication, restarts it, and has the bundled OPC UA client connect and subscribe to every tag to confirm values arrive. See the note under "Running tests" about the settings it leaves behind.
- Custom DeviceHub / Analytics pages: compose your own scenarios or import your own Analytics export.
- Auto test: runs every unlocked test in sequence, settling and observing each phase, and recording the CPU/RAM change. It survives page reloads.
- Snapshot: a one-click export of a self-contained HTML report, or a Word (.docx) report following the team's gateway test report template. The .docx fills in the gateway details table automatically, including network interfaces, serial ports, TPM presence, and hardware version and edge software version. The fields it can't detect are marked in red for you to complete by hand.
- Report Templates page: toggle between the HTML snapshot and Word (.docx) templates, edit either with a live preview against sample data, download a sample .docx, and restore to default any time.
- Cleaner: removes everything the tool created on the gateway, and nothing else. It does not revert the OPC UA server security and authentication settings the OPC UA test changes.
- Themes: switch between light and dark from the header.
Updating
The compose file pins the tool version it shipped with, so docker compose pull on its own won't move you to a newer release. Download the docker-compose.yml for the version you want from the Litmus Central Portal, replace your copy, then:
To run a different version without replacing the compose file, set GWT_VERSION in your .env (or inline for one run):
Troubleshooting
If the Integrations connectors show FAILED, the bundled servers aren't reachable from the gateway. Check the following:
- The servers are running: docker compose ps.
- GWT_SERVERS_HOST is set to the docker host's LAN IP, not localhost, and survived the last restart.
- Ports 4222/5432 aren't firewalled between the gateway and the docker host.
To see the value the running container actually has:
If that comes back empty, the variable was passed inline on an earlier run and wasn't repeated. Put it in a .env file next to docker-compose.yml so it applies every time.
If a large custom scenario fails partway through deploying, the gateway may be taking longer to accept tags than the tool waits. The tool builds several devices at once, which is faster but puts more load on the gateway at the same moment. On a slower gateway, try one of these:
- Lower GWT_DEPLOY_CONCURRENCY (default 4) to build fewer devices at a time, down to 1 to build them one after another.
- Raise GWT_REGISTER_BATCH_TIMEOUT (default 120 seconds) to give each batch of tags longer to land.
- Raise GWT_DEVICE_CREATE_TIMEOUT (default 180 seconds) to give each device longer to be created. Large scenarios can push a single device creation past the default while other devices are being built at the same time.
A failed deploy leaves behind whatever devices it already created. Use Cleaner to remove them before trying again. If a gateway service stops responding mid-clean, Cleaner removes what it can and lists whatever it couldn't under Failed:. That's a partial clean, not a failed one: run it again once the gateway is responding, and check the listed items by hand if they persist.