mrlpy 2.0.0
Python API to MyRobotLab

# 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.