| Name | mrlpy JSON |
| Version |
2.0.0
JSON |
| download |
| home_page | |
| Summary | Python API to MyRobotLab |
| upload_time | 2023-06-28 02:57:14 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MrlPy
This is a native-python API to the MyRobotLab robotics framework. MrlPy uses MRL's webgui service as the API hook point,
and is capable of creating and registering services written in native Python. In addition to this, MrlPy is also capable of
interpreting scripts written for MRL's Jython interpreter.
## Dependencies and Requirements
MrlPy currently depends on requests and websocket-client. It also requires Python 3, and has only been tested under Ubuntu, versions 18.04, 20.04, and 22.04.
## APIs
MrlPy contains three different API tiers: the Command API, the Service API, and the Compatibility API.
### Command API
The lowest of the APIs is the Command API, represented by mrlpy.mcommand. The Command API
can be used for controlling MRL directly, as well as calling service methods and receiving feedback. The most important functions
are mcommand.sendCommand() and mcommand.callService(), leveraging MRL's message API and services API respectively.
mcommand.sendCommand() will return a status code of what happened, while mcommand.callService() will return whatever that service's
called method returned. sendCommand() is asynchronous while callService() is synchronous, as per MRL's documentation. Ex:
```python
from mrlpy import mcommand
print mcommand.callService("runtime", "help", [])
#Prints the help message from runtime
mcommand.sendCommand("runtime", "createAndStart", ["test", "Python"])
#Asynchronously creates a Python service called test.
mcommand.sendCommand("runtime", "shutdown", [])
#Tells mrl to shutdown. No more calls may be made after this
```
### Service API
The Service API is the next API tier. It is responsible for creating, registering, and syncing native Python services
with MRL. In order to write a new service, one only needs to subclass the Service class, found in mrlpy.mservice.
MRL service calls can be made through mcommand.callService(), which also generates a proxy class for a returned service.
For example:
```python
from mrlpy.mservice import MService
from mrlpy import mcommand
class Example(Service):
def __init__(self, name=""):
# ABSOLUTELY REQUIRED TO REGISTER
super(Example, self).__init__(name)
# Create a service function, callable from Java-side via PythonProxy
def test():
ard = mcommand.callService("runtime", "createAndStart", ["ard", "Arduino"])
# Can also use the Compatibility API's org.myrobotlab.service.Runtime proxy
ard.connect("/dev/ttyUSB0")
# This works because mcommand.callService() generates a proxy service for any returned service.
```
### Compatibility API
The Compatibility API is the highest tier. This API was written so that scripts written for MRL's Jython interpreter would still
function. This API exposes the proxy org.myrobotlab.service.Runtime module, enabling calling of MRL's Runtime through the proxy.
The Compatibility API leverages the Service API to provide messaging and proxy service creation.
Compatibility scripts must be ran through the mrlpy.mcompat.MCompatibilityService.
For example, this script is called test.py and was originally written for MRL's Jython interpreter.
```python
ai = Runtime.createAndStart("ai", "ProgramAB")
ai.startSession()
print ai.getResponse("Hello")
```
To run this, open a terminal and type this:
```bash
$ mcompat-run test.py
```
This API is **DEPRECATED** in favor of the Py4j service integrated into MyRobotLab.
## Command-line Utilities
mrlpy includes two command-line utilities: mcommand and mcompat-run. Mcommand allows the user to send any command to a running MRL
instance. Mcompat-run runs a script in compatibility mode, for scripts that were originally written for MRL's Python service. Ex:
```bash
$ mcommand runtime createAndStart test Python
# Asynchronously creates a Python service called test
$ mcompat-run ~/test.py
# Runs the script ~/test.py in compatibility mode.
```
## Configuration
mrlpy can be configured in several ways. The first, and most easiest, is with environment variables. Set MRL_URL to the URL of MRL,
without any leading protocol types or trailing slashes. For example: for localhost, I would do this: export MRL_URL=localhost
For a nonstandard port, use MRL_PORT. Set it to an integer in a valid port range. If these are not defined, mrlpy defaults to
localhost:8888
If configuration at runtime is required, set mrlpy.mcommand.MRL_URL and mrlpy.mcommand.MRL_PORT to the desired values BEFORE calling
any other functions or methods. This includes creating services and running compatibility scripts. These values override environment
variable settings.
Service names can be autogenerated by setting mrlpy.utils.AUTO_GEN_NAMES to true. Names will then change between invocations. If
mrlpy cannot figure out a name, it will autogenerate a name. Services can be created with hard-coded names by passing the name
parameter to the constructor. Ex:
```python
from somewhere import DesiredService
name = "DesiredName"
d = DesiredService(name=name)
# Service is registered with requested name, as long as DesiredService correctly passes the name argument to the superconstructor.
```
## Examples
Example scripts can be found in the examples directory of this repo. These are excluded from PyPi, so they will not be installed along
with the rest of mrlpy.
## Help
To see callable methods / functions and descriptions, open an interactive prompt and type help(whatever). This also works with proxy
instances, although parameter names and method descriptions don't exist.
# Known Issues
1. MrlPy version 2.0 and beyond will only support MyRobotLab Nixie and above with proxy generation patches applies.
2. Proxy classes aren't converted back to json when calling a service method that requires a Service Interface.
Raw data
{
"_id": null,
"home_page": "",
"name": "mrlpy",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "AutonomicPerfectionist <bwtbutler@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b7/af/43b994b56645c5ad72c28a0338671915bc9c046d5e9121f8486e3eccf98b/mrlpy-2.0.0.tar.gz",
"platform": null,
"description": "# MrlPy\nThis is a native-python API to the MyRobotLab robotics framework. MrlPy uses MRL's webgui service as the API hook point,\nand is capable of creating and registering services written in native Python. In addition to this, MrlPy is also capable of\ninterpreting scripts written for MRL's Jython interpreter.\n\n## Dependencies and Requirements\nMrlPy currently depends on requests and websocket-client. It also requires Python 3, and has only been tested under Ubuntu, versions 18.04, 20.04, and 22.04.\n\n## APIs\nMrlPy contains three different API tiers: the Command API, the Service API, and the Compatibility API.\n\n### Command API\nThe lowest of the APIs is the Command API, represented by mrlpy.mcommand. The Command API\ncan be used for controlling MRL directly, as well as calling service methods and receiving feedback. The most important functions\nare mcommand.sendCommand() and mcommand.callService(), leveraging MRL's message API and services API respectively.\nmcommand.sendCommand() will return a status code of what happened, while mcommand.callService() will return whatever that service's\ncalled method returned. sendCommand() is asynchronous while callService() is synchronous, as per MRL's documentation. Ex:\n\n```python\nfrom mrlpy import mcommand\n\nprint mcommand.callService(\"runtime\", \"help\", [])\n#Prints the help message from runtime\n\nmcommand.sendCommand(\"runtime\", \"createAndStart\", [\"test\", \"Python\"])\n#Asynchronously creates a Python service called test.\n\nmcommand.sendCommand(\"runtime\", \"shutdown\", [])\n#Tells mrl to shutdown. No more calls may be made after this\n```\n\n### Service API\nThe Service API is the next API tier. It is responsible for creating, registering, and syncing native Python services\nwith MRL. In order to write a new service, one only needs to subclass the Service class, found in mrlpy.mservice.\nMRL service calls can be made through mcommand.callService(), which also generates a proxy class for a returned service.\nFor example:\n\n```python\nfrom mrlpy.mservice import MService\nfrom mrlpy import mcommand\nclass Example(Service):\n\tdef __init__(self, name=\"\"):\n\t\t# ABSOLUTELY REQUIRED TO REGISTER\n\t\tsuper(Example, self).__init__(name)\n\t# Create a service function, callable from Java-side via PythonProxy\n\tdef test():\n\t\tard = mcommand.callService(\"runtime\", \"createAndStart\", [\"ard\", \"Arduino\"])\n\t\t# Can also use the Compatibility API's org.myrobotlab.service.Runtime proxy\n\n\t\tard.connect(\"/dev/ttyUSB0\")\n\t\t# This works because mcommand.callService() generates a proxy service for any returned service.\n```\n### Compatibility API\nThe Compatibility API is the highest tier. This API was written so that scripts written for MRL's Jython interpreter would still\nfunction. This API exposes the proxy org.myrobotlab.service.Runtime module, enabling calling of MRL's Runtime through the proxy.\nThe Compatibility API leverages the Service API to provide messaging and proxy service creation.\nCompatibility scripts must be ran through the mrlpy.mcompat.MCompatibilityService.\nFor example, this script is called test.py and was originally written for MRL's Jython interpreter.\n```python\nai = Runtime.createAndStart(\"ai\", \"ProgramAB\")\nai.startSession()\nprint ai.getResponse(\"Hello\")\n```\nTo run this, open a terminal and type this:\n```bash\n$ mcompat-run test.py\n```\n\nThis API is **DEPRECATED** in favor of the Py4j service integrated into MyRobotLab.\n\n## Command-line Utilities\nmrlpy includes two command-line utilities: mcommand and mcompat-run. Mcommand allows the user to send any command to a running MRL\ninstance. Mcompat-run runs a script in compatibility mode, for scripts that were originally written for MRL's Python service. Ex:\n\n```bash\n$ mcommand runtime createAndStart test Python\n# Asynchronously creates a Python service called test\n$ mcompat-run ~/test.py\n# Runs the script ~/test.py in compatibility mode.\n```\n\n## Configuration\nmrlpy can be configured in several ways. The first, and most easiest, is with environment variables. Set MRL_URL to the URL of MRL,\nwithout any leading protocol types or trailing slashes. For example: for localhost, I would do this: export MRL_URL=localhost\nFor a nonstandard port, use MRL_PORT. Set it to an integer in a valid port range. If these are not defined, mrlpy defaults to \nlocalhost:8888\n\nIf configuration at runtime is required, set mrlpy.mcommand.MRL_URL and mrlpy.mcommand.MRL_PORT to the desired values BEFORE calling \nany other functions or methods. This includes creating services and running compatibility scripts. These values override environment\nvariable settings.\n\nService names can be autogenerated by setting mrlpy.utils.AUTO_GEN_NAMES to true. Names will then change between invocations. If\nmrlpy cannot figure out a name, it will autogenerate a name. Services can be created with hard-coded names by passing the name\nparameter to the constructor. Ex:\n\n```python\nfrom somewhere import DesiredService\n\nname = \"DesiredName\"\nd = DesiredService(name=name)\n# Service is registered with requested name, as long as DesiredService correctly passes the name argument to the superconstructor.\n```\n\n## Examples\nExample scripts can be found in the examples directory of this repo. These are excluded from PyPi, so they will not be installed along\nwith the rest of mrlpy.\n\n## Help\nTo see callable methods / functions and descriptions, open an interactive prompt and type help(whatever). This also works with proxy\ninstances, although parameter names and method descriptions don't exist.\n\n# Known Issues\n1. MrlPy version 2.0 and beyond will only support MyRobotLab Nixie and above with proxy generation patches applies.\n2. Proxy classes aren't converted back to json when calling a service method that requires a Service Interface.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python API to MyRobotLab",
"version": "2.0.0",
"project_urls": {
"Homepage": "http://github.com/AutonomicPerfection/mrlpy"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f81762855afa9c1b76fc68190b8657ce541b9effcc78d105f6ff2ee2a5e9ebf",
"md5": "bfa67ae9c45baa3e6edacbff6fc84595",
"sha256": "a829c13f10ea6462c132843e3f278614deb7a43e0efeeb0c73321f9ad1b34e37"
},
"downloads": -1,
"filename": "mrlpy-2.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "bfa67ae9c45baa3e6edacbff6fc84595",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 23222,
"upload_time": "2023-06-28T02:57:13",
"upload_time_iso_8601": "2023-06-28T02:57:13.406419Z",
"url": "https://files.pythonhosted.org/packages/4f/81/762855afa9c1b76fc68190b8657ce541b9effcc78d105f6ff2ee2a5e9ebf/mrlpy-2.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b7af43b994b56645c5ad72c28a0338671915bc9c046d5e9121f8486e3eccf98b",
"md5": "ba14450a309e56543596ca2bee5197e0",
"sha256": "a35073b36736b8cae3aed1559b0ca49b119023f5cd3ab14cf804887e09de7f0e"
},
"downloads": -1,
"filename": "mrlpy-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ba14450a309e56543596ca2bee5197e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22090,
"upload_time": "2023-06-28T02:57:14",
"upload_time_iso_8601": "2023-06-28T02:57:14.860978Z",
"url": "https://files.pythonhosted.org/packages/b7/af/43b994b56645c5ad72c28a0338671915bc9c046d5e9121f8486e3eccf98b/mrlpy-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-28 02:57:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AutonomicPerfection",
"github_project": "mrlpy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mrlpy"
}
