Python reference implementation of the Laboratory Experiment COntrol (LECO) protocol.
Note: LECO is still under development, such that the code and API might change. The LECO protocol branch pyleco-state contains the assumptions used in this project, which are not yet accepted into the LECO main branch. See this documentation for the LECO definitions including these assumptions. These things might change, if LECO defines them differently.
For a tutorial on how to get started, see GETTING_STARTED.md.
You are welcome to contribute, for more information see CONTRIBUTING.md.
pip install pyleco
or conda install conda-forge::pyleco
,pyleco
in your python scripts,PyLECO is an implementation of LECO, for the full protocol specifications please visit https://github.com/pymeasure/leco-protocol. LECO offers a protocol for data exchange, for example for laboratory experimental control.
There exist two different communication protocols in LECO.
A LECO network needs at least one Coordinator (server), which routes the messages among the connected Components.
Each Component has a name unique in the network.
This name consists in the name of the Coordinator they are connected to and their own name.
For example N1.component1
is the full name of component1
connected to the Coordinator of the Namespace N1
.
That Coordinator itself is called N1.COORDINATOR
, as Coordinators are always called COORDINATOR
.
The default messaging content of the control protocol are remote procedure calls (RPC) according to JSON-RPC.
RPC means, that you execute a method (or procedure) on a remote Component.
For example you have an Actor, which is for example a Component controlling a measurement instrument.
In order to set the output of that measurement instrument, you want to call the set_output
method of that instrument.
For that purpose, you send a message which encodes exactly that (via jsonrpc): the method to call and the parameters of that method.
For a minimum setup, you need:
coordinator
in your terminal or run the coordinator.py
file with your Python interpreter),For example, you can use a Communicator
instance to send/receive messages via LECO protocol.
The following example requests the list of Components connected currently to the Coordinator:
from pyleco.utils.communicator import Communicator
c = Communicator(name="TestCommunicator")
connected_components = c.ask_rpc(method="send_local_components")
print(connected_components)
Let's say you have an instrument with a pymeasure driver Driver
, which you want to control.
You need to start (in different threads):
Actor
instance listening to commands and controlling the instrument: actor = Actor(name="inst_actor", cls=Driver)
.
For an example see the pymeasure_actor.py
in the examples folder,TransparentDirector
: director=TransparentDirector(actor="inst_actor")
. The actor
parameter has to match the Actor's name
parameter.
For an example of a measurement script see measurement_script.py
in the examples folder.If you want to set some property of the instrument (e.g. instrument.voltage = 5
), you can just use the director
transparently: director.device.voltage = 5
.
In the background, the TransparentDirector, which does not have a device
, sends a message to the Actor to set that parameter.
The Actor in turn sets that parameter of the instrument driver, which in turn will send some command to the device to take an appropriate action (e.g. setting the voltage to 5 V).
Currently you cannot call methods in a similar, transparent way, without manual intervention.
You can add RemoteCall
descriptor (in transparent_director module) to the director
for each method call you want to use.
Afterwards you can use these methods transparently similar to the property shown above.
PyLECO offers the following subpackages and modules. For more information and for examples see the docstrings of the relevant methods and classes.
core
subpackage contains elements necessary for implementing LECO and for interacting with PyLECO, for example:
Message
and DataMessage
class help to create and interpret LECO messages for the control and broadcasting protocol, respectively.leco_protocols
module contains Protocol classes for the different LECO Components, in order to test, whether a Component satisfies the LECO standard for communicating with other programs.internal_protocols
module contains Protocol classes which define the API access to PyLECO.utils
subpackage contains modules useful for creating LECO Components.
Communicator
can send and receive messages, but neither blocks (just for a short time waiting for an answer) nor requires an extra thread.
It satisfies the CommunicatorProtocol
and is useful in scripts.MessageHandler
also satisfies the CommunicatorProtocol
, but handles incoming messages in a continuous loop (blocking until stopped).
It is useful for creating standalone scripts, like tasks for the Starter.ExtendedMessageHandler
adds the capability to subscribe and receive data protocol messages.Listener
offers an interface according to the CommunicatorProtocol
, but listens at the same time in an extra thread for incoming messages (with an ExtendedMessageHandler
).
It is useful if you want to react to incoming messages (via data or control protocol) and if you want to send messages of your own accord, for example for GUI applications.coordinators
subpackage contains the different Coordinators.
Coordinator
is the Coordinator for the control protocol (exchanging messages).proxy_server
is the Coordinator for the data protocol (broadcasting).actors
subpackage contains Actor classes to control devices.management
subpackage contains Components useful for experiment management.
Starter
can execute tasks in separate threads.
A task could be an Actor controlling some Device.DataLogger
listens to published data (via the data protocol) and collects them.directors
subpackage contains Directors, which facilitate controlling actors or management utilities.
Director
is a base Director.
It can communicate via any util, which implements the CommunicatorProtocol
.CoordinatorDirector
has a method for getting Coordinators and Components connected to a Coordinator.TransparentDirector
reads / writes all messages to the remote actor, such that you use the director's device
as if it were the instrument itself.The pyleco-extras package contains additional modules.
Among them are GUIs controlling the DataLogger
and the Starter
.