Welcome to PdCom5’s documentation!¶
How to install¶
You can install PdCom5 using pip: pip3 install pdcom5. The sources can be found here on GitLab. They can be used to build PdCom5 on your own if the packages provided on PyPI or Linux package repositories don’t suit you.
Quickstart¶
The counterpart of PdCom is PdServ which ships an example application. This can be used for exploring the Python interface of PdCom5 if you don’t have your own PdServ application.
Please note that this Python API is based on asyncio, so uses a lot of coroutines (these things with async and await). But if you have Python >= 3.8, you can still use this library interactively on the CLI by starting the asyncio REPL: python3 -m asyncio.
The starting point for almost everything is the Process class
which is in charge of handling the communication.
You can use it to find variables, to set parameters and to subscribe to signals.
In this snippet, a connection is made to the oscillator example in PdServ. Its cosine output is subscribed to with a period of one second. The value is printed five times, then the enable Parameter is set to False. After that, the cosine output is polled twice.
>>> import pdcom5
>>> process = pdcom5.Process()
>>> await process.connect("msr://localhost:2345")
>>> variable = await process.find("/osc/cos")
>>> variable.shape
(1,)
>>> sub = await process.subscribe(1.0, variable)
>>> for i in range(5):
... await sub.read()
...
(8.78446130364271, datetime.timedelta(days=19459, seconds=29086, microseconds=437320))
(7.851994244479773, datetime.timedelta(days=19459, seconds=29087, microseconds=437407))
(-3.094420865989016, datetime.timedelta(days=19459, seconds=29088, microseconds=437398))
(-10.094402900214018, datetime.timedelta(days=19459, seconds=29089, microseconds=437408))
(-4.220607508690086, datetime.timedelta(days=19459, seconds=29090, microseconds=437397))
>>> await process.setVariableValue("/osc/enable", False)
>>> await variable.poll()
(-2.7455815235765124, datetime.timedelta(days=19459, seconds=29159, microseconds=877336))
>>> await variable.poll()
(-2.7455815235765124, datetime.timedelta(days=19459, seconds=29160, microseconds=817388))
There is also Transmission.event_mode and
Transmission.poll_mode for creating non-periodical subscriptions.
Authentication¶
Username and Password can be passed in the url given to Process.connect(),
for example msr://username:passwort@localhost.
If username contains an at sign (@), it has to be escaped using %40.
If login is mandatory and no credentials were supplied,
LoginRequired is thrown when calling Process.connect().
LoginFailed is raised in case login has not been successful.
TLS Encryption¶
When using the msrs scheme, TLS will be used to encrypt the communication.
If the Certificate Authory (CA) which signed the public certificate
of the PdServ instance is not installed on your machine,
you can provide your own ssl.SSLContext.
>>> import ssl
>>> ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> ctx.load_verify_locations("/path/to/ca.pem")
>>> ctx.verify_mode = ssl.CERT_REQUIRED
>>> ctx.check_hostname = True
>>> import pdcom5
>>> process = pdcom5.Process()
>>> await process.connect("msrs://localhost", ctx)
You can also use the ssl.SSLContext to provide User Certificates,
they can be used for TLS Client Authentication.
How to find the PdCom Version¶
In the pdcom5 module, the variable full_version contains the version of the PdCom5 library. If you have any questions or report a bug, please include this version information in your request.
$ python3 -c "import pdcom5; print(pdcom5.full_version)"
5.1.0.8.gea62937+