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.
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.
MrlPy contains three different API tiers: the Command API, the Service API, and the Compatibility 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:
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 thisThe 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 MService 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:
from mrlpy.mservice import MService
from mrlpy import mcommand
class Example(MService):
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.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.
ai = Runtime.createAndStart("ai", "ProgramAB")
ai.startSession()
print ai.getResponse("Hello")To run this, open a terminal and type this:
$ mcompat-run test.pymrlpy 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:
$ mcommand runtime createAndStart test Python
#Asynchronously creates a Python service called test
$ mcompat-run ~/test.py
#Runs the script ~/test.py in compatibility mode.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.mutils.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:
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.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.
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.
- Messaging to and from Message API only implemented in this project. PythonProxy has yet to implement the other half
- Proxy classes aren't converted back to json when calling a service method that requires a Service Interface.