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:

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:

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.

ai = Runtime.createAndStart("ai", "ProgramAB")
ai.startSession()
print ai.getResponse("Hello")

To run this, open a terminal and type this:

$ 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:

$ 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:

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.