| Name | pyleco JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | Python reference implementation of the Laboratory Experiment COntrol (LECO) protocol |
| upload_time | 2025-02-12 14:43:43 |
| maintainer | None |
| docs_url | None |
| author | PyLECO Developers |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023-2025 PyLECO Developers Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PyLECO
[](https://codecov.io/gh/pymeasure/pyleco)
[](https://pypi.org/project/pyleco/)
[](https://anaconda.org/conda-forge/pyleco)
[](https://zenodo.org/doi/10.5281/zenodo.10837366)
[](https://common-changelog.org)
Python reference implementation of the [Laboratory Experiment COntrol (LECO) protocol](https://github.com/pymeasure/leco-protocol).
**Note**: LECO is still under development, such that the code and API might change.
The LECO protocol branch [pyleco-state](https://github.com/pymeasure/leco-protocol/tree/pyleco-state) contains the assumptions used in this project, which are not yet accepted into the LECO main branch.
See this [documentation](https://leco-laboratory-experiment-control-protocol--69.org.readthedocs.build/en/69/) 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](https://github.com/pymeasure/pyleco/blob/main/GETTING_STARTED.md).
You are welcome to contribute, for more information see [CONTRIBUTING.md](https://github.com/pymeasure/pyleco/blob/main/CONTRIBUTING.md).
## Quick Start
1. Install Python,
2. install PyLECO with `pip install pyleco` or `conda install conda-forge::pyleco`,
3. import the package `pyleco` in your python scripts,
4. and use it as desired.
## LECO Overview
### Network Topology
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.
1. The control protocol allows to exchange messages between any two _Components_ in a LECO network, which is useful for controlling devices.
2. The data protocol is a broadcasting protocol to send information to all those, who want to receive it, which is useful for regular measurement data or for log entries.
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`.
### Remote Procedure Calls
The default messaging content of the control protocol are _remote procedure calls_ (RPC) according to [JSON-RPC](https://www.jsonrpc.org/specification).
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.
## Usage of the Control Protocol
### Minimum Setup
For a minimum setup, you need:
* a _Coordinator_ (just execute `coordinator` in your terminal or run the `coordinator.py` file with your Python interpreter),
* one _Component_.
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_:
```python
from pyleco.utils.communicator import Communicator
c = Communicator(name="TestCommunicator")
connected_components = c.ask_rpc(method="send_local_components")
print(connected_components)
```
### Instrument Control
Let's say you have an instrument with a pymeasure driver `Driver`, which you want to control.
You need to start (in different threads):
* a _Coordinator_ (as described above),
* an `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,
* a `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.
## Overview of Offered Packages and Modules
PyLECO offers the following subpackages and modules.
For more information and for examples see the docstrings of the relevant methods and classes.
* The `core` subpackage contains elements necessary for implementing LECO and for interacting with PyLECO, for example:
* The `Message` and `DataMessage` class help to create and interpret LECO messages for the control and broadcasting protocol, respectively.
* The `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.
* The `internal_protocols` module contains _Protocol_ classes which define the API access to PyLECO.
* The `utils` subpackage contains modules useful for creating LECO Components.
* The`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.
* The `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_.
* The `ExtendedMessageHandler` adds the capability to subscribe and receive data protocol messages.
* The `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.
* The `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).
* The `actors` subpackage contains _Actor_ classes to control devices.
* The `management` subpackage contains _Components_ useful for experiment management.
* The `Starter` can execute tasks in separate threads.
A task could be an _Actor_ controlling some _Device_.
* The `DataLogger` listens to published data (via the data protocol) and collects them.
* The `directors` subpackage contains Directors, which facilitate controlling actors or management utilities.
* The `Director` is a base _Director_.
It can communicate via any util, which implements the `CommunicatorProtocol`.
* For example the `CoordinatorDirector` has a method for getting _Coordinators_ and _Components_ connected to a _Coordinator_.
* The `TransparentDirector` reads / writes all messages to the remote actor, such that you use the director's `device` as if it were the instrument itself.
### PyLECO extras
The [pyleco-extras](https://github.com/BenediktBurger/pyleco-extras) package contains additional modules.
Among them are GUIs controlling the `DataLogger` and the `Starter`.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyleco",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "PyLECO Developers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c7/1a/f9c0b666357d9da998367e01b0c7fdc22778335b3312ec1e2491c6749d0c/pyleco-0.4.1.tar.gz",
"platform": null,
"description": "# PyLECO\n\n\n[](https://codecov.io/gh/pymeasure/pyleco)\n[](https://pypi.org/project/pyleco/)\n[](https://anaconda.org/conda-forge/pyleco)\n[](https://zenodo.org/doi/10.5281/zenodo.10837366)\n[](https://common-changelog.org)\n\nPython reference implementation of the [Laboratory Experiment COntrol (LECO) protocol](https://github.com/pymeasure/leco-protocol).\n\n**Note**: LECO is still under development, such that the code and API might change.\nThe LECO protocol branch [pyleco-state](https://github.com/pymeasure/leco-protocol/tree/pyleco-state) contains the assumptions used in this project, which are not yet accepted into the LECO main branch.\nSee this [documentation](https://leco-laboratory-experiment-control-protocol--69.org.readthedocs.build/en/69/) for the LECO definitions including these assumptions.\nThese things might change, if LECO defines them differently.\n\nFor a tutorial on how to get started, see [GETTING_STARTED.md](https://github.com/pymeasure/pyleco/blob/main/GETTING_STARTED.md).\n\nYou are welcome to contribute, for more information see [CONTRIBUTING.md](https://github.com/pymeasure/pyleco/blob/main/CONTRIBUTING.md).\n\n\n## Quick Start\n\n1. Install Python,\n2. install PyLECO with `pip install pyleco` or `conda install conda-forge::pyleco`,\n3. import the package `pyleco` in your python scripts,\n4. and use it as desired.\n\n\n## LECO Overview\n\n### Network Topology\n\nPyLECO is an implementation of LECO, for the full protocol specifications please visit https://github.com/pymeasure/leco-protocol.\nLECO offers a protocol for data exchange, for example for laboratory experimental control.\n\nThere exist two different communication protocols in LECO.\n1. The control protocol allows to exchange messages between any two _Components_ in a LECO network, which is useful for controlling devices.\n2. The data protocol is a broadcasting protocol to send information to all those, who want to receive it, which is useful for regular measurement data or for log entries.\n\nA LECO network needs at least one _Coordinator_ (server), which routes the messages among the connected Components.\n\nEach _Component_ has a name unique in the network.\nThis name consists in the name of the _Coordinator_ they are connected to and their own name.\nFor example `N1.component1` is the full name of `component1` connected to the _Coordinator_ of the _Namespace_ `N1`.\nThat _Coordinator_ itself is called `N1.COORDINATOR`, as _Coordinators_ are always called `COORDINATOR`.\n\n### Remote Procedure Calls\n\nThe default messaging content of the control protocol are _remote procedure calls_ (RPC) according to [JSON-RPC](https://www.jsonrpc.org/specification).\nRPC means, that you execute a method (or procedure) on a remote _Component_.\nFor example you have an Actor, which is for example a Component controlling a measurement instrument.\nIn order to set the output of that measurement instrument, you want to call the `set_output` method of that instrument.\nFor that purpose, you send a message which encodes exactly that (via jsonrpc): the method to call and the parameters of that method.\n\n\n## Usage of the Control Protocol\n\n### Minimum Setup\n\nFor a minimum setup, you need:\n* a _Coordinator_ (just execute `coordinator` in your terminal or run the `coordinator.py` file with your Python interpreter),\n* one _Component_.\n\nFor example, you can use a `Communicator` instance to send/receive messages via LECO protocol.\nThe following example requests the list of _Components_ connected currently to the _Coordinator_:\n\n```python\nfrom pyleco.utils.communicator import Communicator\n\nc = Communicator(name=\"TestCommunicator\")\nconnected_components = c.ask_rpc(method=\"send_local_components\")\nprint(connected_components)\n```\n\n### Instrument Control\n\nLet's say you have an instrument with a pymeasure driver `Driver`, which you want to control.\n\nYou need to start (in different threads):\n* a _Coordinator_ (as described above),\n* an `Actor` instance listening to commands and controlling the instrument: `actor = Actor(name=\"inst_actor\", cls=Driver)`.\n For an example see the `pymeasure_actor.py` in the examples folder,\n* a `TransparentDirector`: `director=TransparentDirector(actor=\"inst_actor\")`. The `actor` parameter has to match the Actor's `name` parameter.\n For an example of a measurement script see `measurement_script.py` in the examples folder.\n\nIf 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`.\nIn the background, the TransparentDirector, which does not have a `device`, sends a message to the Actor to set that parameter.\nThe 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).\n\nCurrently you cannot call methods in a similar, transparent way, without manual intervention.\nYou can add `RemoteCall` descriptor (in transparent_director module) to the `director` for each method call you want to use.\nAfterwards you can use these methods transparently similar to the property shown above.\n\n\n## Overview of Offered Packages and Modules\n\nPyLECO offers the following subpackages and modules.\nFor more information and for examples see the docstrings of the relevant methods and classes.\n\n* The `core` subpackage contains elements necessary for implementing LECO and for interacting with PyLECO, for example:\n * The `Message` and `DataMessage` class help to create and interpret LECO messages for the control and broadcasting protocol, respectively.\n * The `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.\n * The `internal_protocols` module contains _Protocol_ classes which define the API access to PyLECO.\n* The `utils` subpackage contains modules useful for creating LECO Components.\n * The`Communicator` can send and receive messages, but neither blocks (just for a short time waiting for an answer) nor requires an extra thread.\n It satisfies the `CommunicatorProtocol` and is useful in scripts.\n * The `MessageHandler` also satisfies the `CommunicatorProtocol`, but handles incoming messages in a continuous loop (blocking until stopped).\n It is useful for creating standalone scripts, like tasks for the _Starter_.\n * The `ExtendedMessageHandler` adds the capability to subscribe and receive data protocol messages.\n * The `Listener` offers an interface according to the `CommunicatorProtocol`, but listens at the same time in an extra thread for incoming messages (with an `ExtendedMessageHandler`).\n 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.\n* The `coordinators` subpackage contains the different _Coordinators_.\n * `Coordinator` is the _Coordinator_ for the control protocol (exchanging messages).\n * `proxy_server` is the _Coordinator_ for the data protocol (broadcasting).\n* The `actors` subpackage contains _Actor_ classes to control devices.\n* The `management` subpackage contains _Components_ useful for experiment management.\n * The `Starter` can execute tasks in separate threads.\n A task could be an _Actor_ controlling some _Device_.\n * The `DataLogger` listens to published data (via the data protocol) and collects them.\n* The `directors` subpackage contains Directors, which facilitate controlling actors or management utilities.\n * The `Director` is a base _Director_.\n It can communicate via any util, which implements the `CommunicatorProtocol`.\n * For example the `CoordinatorDirector` has a method for getting _Coordinators_ and _Components_ connected to a _Coordinator_.\n * The `TransparentDirector` reads / writes all messages to the remote actor, such that you use the director's `device` as if it were the instrument itself.\n\n### PyLECO extras\n\nThe [pyleco-extras](https://github.com/BenediktBurger/pyleco-extras) package contains additional modules.\nAmong them are GUIs controlling the `DataLogger` and the `Starter`.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023-2025 PyLECO Developers Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Python reference implementation of the Laboratory Experiment COntrol (LECO) protocol",
"version": "0.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/pymeasure/pyleco/issues",
"Homepage": "https://github.com/pymeasure/pyleco"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "39d047cc78c11bdd3edcff33bb34f0ac0e2433aa8367df2629e891d4d06f4201",
"md5": "67d943f6ea1e49f8f70b526267c7e129",
"sha256": "b134188f9b761f97a783df0efb6cf339b5c75ac9e355fec346118818b0850cdb"
},
"downloads": -1,
"filename": "pyleco-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67d943f6ea1e49f8f70b526267c7e129",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 105561,
"upload_time": "2025-02-12T14:43:41",
"upload_time_iso_8601": "2025-02-12T14:43:41.118410Z",
"url": "https://files.pythonhosted.org/packages/39/d0/47cc78c11bdd3edcff33bb34f0ac0e2433aa8367df2629e891d4d06f4201/pyleco-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c71af9c0b666357d9da998367e01b0c7fdc22778335b3312ec1e2491c6749d0c",
"md5": "74c602158adc689a4df6dc641f49e094",
"sha256": "037a67ae7bc4c0fbdf551a295854556552a24e328f9ba2fb41d2b1bdff506e3d"
},
"downloads": -1,
"filename": "pyleco-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "74c602158adc689a4df6dc641f49e094",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 132004,
"upload_time": "2025-02-12T14:43:43",
"upload_time_iso_8601": "2025-02-12T14:43:43.564809Z",
"url": "https://files.pythonhosted.org/packages/c7/1a/f9c0b666357d9da998367e01b0c7fdc22778335b3312ec1e2491c6749d0c/pyleco-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 14:43:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pymeasure",
"github_project": "pyleco",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyleco"
}
