--- title: Gateway Functionality Testing User Guide slug: solutions/gateway-functionality-testing-user-guide docTags: createdAt: 2026-08-13T23:15:14.811Z --- 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](https://portal.litmus.io/) and install it following the [ISO Installation on an Industrial PC (IPC)](docId\:blDXZrjtg_SGSXjgYT2sk) guide. - **The docker-compose.yml file**: download it from the [Litmus Central Portal](https://portal.litmus.io/). 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](https://portal.litmus.io/) instead and load it with `docker load -i .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 :::BlockQuote docker compose --profile servers up -d ::: 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](https://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`: :::BlockQuote COMPOSE\_PROFILES=servers GWT\_SERVERS\_HOST=192.168.1.20 ::: 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: :::BlockQuote GWT\_SERVERS\_HOST=192.168.1.20 docker compose --profile servers up -d ::: 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: 1. Enter the gateway's IP address or hostname in **Gateway address** (just the IP/hostname; https is assumed). 2. Pick an auth method (**Username / password**, **API token**, or **First login**) and fill in the matching fields (for example, username and password). 3. Leave **Allow self-signed certificate** checked if the gateway uses a self-signed cert. 4. 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: 1. 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. 2. 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. 1. Run the tests that apply to your setup: the individual component tests, or *Auto test* to run the full sequence in one go. 2. 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. 3. 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: 1. Email the completed report to `gatewaytesting@litmus.io`. Attach the .docx, send one gateway model per email, and use the subject line `Gateway test report: - `. 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. 2. 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](https://portal.litmus.io/), replace your copy, then: :::BlockQuote docker compose pull docker compose up -d ::: To run a different version without replacing the compose file, set `GWT_VERSION` in your .env (or inline for one run): :::BlockQuote GWT\_VERSION=1.1.0 docker compose up -d ::: ## 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: :::BlockQuote docker compose exec gateway-testing env | grep GWT\_SERVERS\_HOST ::: 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. :::BlockQuote GWT\_DEPLOY\_CONCURRENCY=1 docker compose up -d ::: 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.