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 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 \<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 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 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 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 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 gatewaytesting\@litmus io 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 https //portal litmus io/ , replace your copy, then 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) 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 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 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