This release is a pre-release and may not be stable for production use.
dls_plc_tools
Tools for interrogating Omron NX PLCs over EtherNet/IP, to support EPICS commissioning of PLC-based vacuum systems at Diamond Light Source.
They let you browse the tags a PLC publishes, inspect the layout of its
structures, and watch values update live — without a Sysmac Studio licence or
physical access to the controller. Everything is read-only explicit
messaging: the same mechanism the EPICS ether_ip driver uses, serviced in
the controller's spare time, so it is safe to run against production PLCs.
There are two front-ends over the aphyt
library: a command-line tool (dls-plc-tools read) and a PySide6 desktop GUI
(dls-plc-tools gui) — both subcommands of the single dls-plc-tools command,
so you can run either without installing, e.g. uvx dls-plc-tools gui 172.23.x.x.
| What | Where |
|---|---|
| Source | https://github.com/DiamondLightSource/dls-plc-tools |
| PyPI | pip install dls-plc-tools |
| Docker | docker run ghcr.io/diamondlightsource/dls-plc-tools:latest |
| Releases | https://github.com/DiamondLightSource/dls-plc-tools/releases |
Command-line tool
With just an IP address, dls-plc-tools read discovers every published
structure tag on the PLC and summarises each one — its member layout and how
many instances are actually in use:
dls-plc-tools read 172.23.x.x
Other modes:
dls-plc-tools read 172.23.x.x -l # list every published tag and its type
dls-plc-tools read 172.23.x.x -s Seq # show one structure's members and array bounds
dls-plc-tools read 172.23.x.x -d Seq # live-updating table of a structure's values
dls-plc-tools read 172.23.x.x -d Seq -m Desc,State,Status # choose which members to watch
dls-plc-tools read 172.23.x.x -p Temp # diagnose a structure that fails to decode
--probe/-p is for the case where reading one tag fails inside aphyt: it
reports the read chunk by chunk, how the structure's members map onto the bytes
that came back, and which member is the one that cannot be decoded.
--detail/-d redraws a table every 2 seconds (floor 0.5 s, set with
--interval), highlighting cells that have changed. Press Ctrl-C to stop. See
dls-plc-tools read --help for the full option list.
GUI
dls-plc-tools gui 172.23.x.x
dls-plc-tools gui gives you a browsable list of the PLC's published tags, a live
table of a selected structure's values (changed cells flash amber), and an
export of the discovered structure layouts to an Excel spreadsheet. The IP
address argument is optional — you can also enter it in the window.
Reaching a PLC on a private network (port forwarding)
Some PLCs sit on a private per-CIA network (192.168.<cell>.0/24) reachable only
from the cluster's worker nodes, not from a normal workstation. Tick Port
forward in the GUI to enable the extra fields and connect via a temporary
socat forward on the (acastus) cluster:
- Node — the worker node with access to that private network. Ticking Port
forward fetches the cluster's live node list (
kubectl get nodes) into the dropdown, so it always reflects the current nodes; if you're not logged in yet it falls back to a staticsr01c…sr24clist and shows the error. The combo is editable, so you can type over it for any other node. - Service IP — a fixed-pool IP for the forward's LoadBalancer, or a DNS name
that resolves to one (the dropdown offers
sr01c-pfwd…sr24c-pfwd, also editable). A name is resolved to its IP before use; that resolved IP is the address the GUI then connects to. - Port — the port forwarded on both sides, defaulting to the EtherIP port 44818.
On Connect the tool first checks nobody else already forwards
service_ip:port (it won't clobber another user's forward), then stands up a
throwaway socat pod + LoadBalancer service (service_ip:port → plc_ip:port,
pinned to the node) and connects to the Service IP; Disconnect (and closing
the window) tears both down. The Pod indicator by the buttons shows the
forward's state — red inactive, orange pending (standing up), green good
(up and reachable) — alongside the pod name (pfwd-<user>-<port>) so you can
trace it with kubectl get pod <name> -n accelerator. This path needs kubectl
and the acastus klogin, so it only works on a DLS workstation. Leave Port
forward unticked to connect directly to the IP, as before.
Every field can be prefilled from the command line, which also ticks the box — handy for a specific cell. This opens the GUI ready to connect to the sr19c PLC through its forward:
dls-plc-tools gui 192.168.19.10 --port-forward \
--node sr19c-k8s-serv-01.pri.diamond.ac.uk --service-ip sr19c-pfwd
--service-ip takes an IP or a DNS name, --port overrides 44818, -f is
short for --port-forward, and --cluster (default acastus) selects which
cluster's klogin to source. See dls-plc-tools gui --help for all options.
The Service IP is normally already owned by a permanent per-node forward that
exposes other services on the same fixed IP (e.g. the sr19c-pfwd Helm release
under common-services/). Sharing one LoadBalancer IP between that service and
this tool's needs MetalLB's metallb.universe.tf/allow-shared-ip annotation set
to the same key on both — the chart and the tool both key it on the IP itself, so
they match automatically, as long as the permanent service carries the
annotation.
Log into acastus first. The tool has no login of its own — it reuses your shell's cluster credentials. Authenticate in a terminal before launching the GUI (source the acastus klogin and log in, e.g.
kubectl get pods -n accelerator), then start the GUI from the same account. If your login is missing or expired, the forward step fails fast with a clear "not logged into acastus … log in in a terminal, then retry" message in the status bar (a preflightkubectl auth whoamicheck), rather than hanging. If you hit persistent auth errors, runklogoutand log in again.
Installation
pip install dls-plc-tools
Or, for development, using uv:
git clone https://github.com/DiamondLightSource/dls-plc-tools.git
cd dls-plc-tools
uv sync
uv run dls-plc-tools read <ip>
Notes
- These tools only ever read. They never write to the controller, never start a keep-alive poll, and keep at most one request in flight. Poll rates default to ~2 s and are floored at 0.5 s.
- Tags are visible over EtherNet/IP only if they are globals with Network
Publish set in Sysmac Studio, plus the controller's
_-prefixed system variables. Enumeration uses Omron's Tag Name Server object (CIP class 0x6A). - DLS structures are structure-of-arrays:
Seq.Interfc[1]is instance 1, with index 0 reserved as padding. A non-emptyDescentry marks an instance that is actually in use. - Values read with 1.0.0b5 or earlier may be wrong.
aphytmis-calculates how many bytes aBOOLarray occupies for some array lengths, and every member declared after such an array in the same structure was then read from the wrong offset — silently, unless the error grew large enough to run off the end of the data and raise. This release corrects the calculation. If you have spreadsheets or notes taken from an earlier version, re-export them.
Metadata
Release files for dls-plc-tools 1.0.0b7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dls_plc_tools-1.0.0b7.tar.gz | 134.6 kB | Without provenance | Details for dls_plc_tools-1.0.0b7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dls_plc_tools-1.0.0b7-py3-none-any.whl | Python 3 | none | any | Details for dls_plc_tools-1.0.0b7-py3-none-any.whl |
Total release size: 181.3 kB
Release files / dls_plc_tools-1.0.0b7.tar.gz
| Download URL | dls_plc_tools-1.0.0b7.tar.gz |
|---|---|
| Size | 134.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fdfabaabc478805c4e07df8421db6ac2c0a6bb9c7031e1cde4c51251084afdf5
|
|
BLAKE2b-256 checksum How to use checksums |
a37d77e96f8722713f5b941cefeb7bbc83ca563fa23ec9d5f3355182ec8ae902
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / dls_plc_tools-1.0.0b7-py3-none-any.whl
| Download URL | dls_plc_tools-1.0.0b7-py3-none-any.whl |
|---|---|
| Size | 46.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
71f39fd23122aea67f0032d7dbff5dfae727745b573d1ea64743466eccf71bdf
|
|
BLAKE2b-256 checksum How to use checksums |
43d879d6d511cd50736f33a504f34ecd22679193e6feca8728d2904165a7e985
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for dls-plc-tools 1.0.0b7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.