MIRA
Toolbox Python - Documentation


The python toolbox allows to use MIRA's framework functionality in python and to use python inside MIRA.

The mirapy module

There are three ways to use MIRA in python. The first is by booting up an own framework in python and launch units from script. The second way is to use the python interpreter from inside an already existing framework and launch units from script. The last way is to use the <pyunit> tag in the config files to launch a python unit in a framework. You should add the follwing path(s) to the PYTHONPATH environment variable in order to use the mirapy and service modules directly from python:

Use an own framework

One can use MIRA inside a python console by adding the MIRADIR folders to the python module search path (PYTHONPATH). After that the mirapy module can be imported like any other module and a framework can be created. Note that there can be only one instance of a framework and an exception will be thrown if one attempts to create second one.

import mirapy
args = ["-d3","-p1234"] # or ["-d", "3","-p", "1234"], do not use extra whitespace in both cases!
fw = mirapy.Framework(args)
fw.load() # load all configs given by command line
#fw.load("myconfig.xml")
#fw.load("anotherconfig.xml")
fw.start() # start up the framework
fw.loop() # run until interrupted

In the above example you can see that the frameworks constructor takes the command line arguments. The load() method loads all config files given on the command line arguments. One can also load additional configuration files via the load(file) method. The framework needs to be started to start up units. Optional you can enter an infinite loop until the user signals an interruption request (e.g. Ctrl-C)

Units

The mirapy module contains a Unit class that can be inherited and provides nearly the same functionality as the C++ counterpart (See Unit)

import mirapy
class MyUnit(mirapy.Unit):
def __init__(self):
super(MyUnit, self).__init__()
def reflect(self,r):
"Called by different reflectors"
pass
def initialize(self):
"Called once on startup of the unit"
pass
def process(self):
"Called every 250 milliseconds (see checkin)"
pass
def finalize(self):
"Called once when unit is going to be destructed"
pass
u = MyUnit()
u.checkin("/", "Test", mirapy.milliseconds(250))

The mirapy.Unit class also has some predefined functions for accessing channels and RPC services.

The reflectors support members, properties, roproperties, methods and interfaces. Members and (ro)properties must be registered using getters and setters (no setter for roproperty) and a type. Lists can be used as members or (ro)properties with the [type] syntax:

import mirapy
class MyUnit(mirapy.Unit):
def __init__(self):
super(MyUnit, self).__init__()
self.offset = 50
self.myList = ["A", "B", "C"]
def setOffset(self, value):
self.offset = value
def getOffset(self):
return self.offset
def setList(self, value):
self.myList = value
def getList(self):
return self.myList
def helloWorld(self, s):
print(s)
def sum(self,a,b):
return a+b
def initialize(self):
self.publishService()
def reflect(self,r):
r.property("Offset", int, self.getOffset, self.setOffset, "some offset")
r.property("List", [str], self.getList, self.setList, "a list of things")
r.voidMethod("helloWorld", self.helloWorld, "Prints the message given in the parameter", "s", "The message", "hi")
r.method("sum", self.sum, "Return sum of 2 summands", "a", "Summand a", 1.0, "b", "Summand b", 2.0)
r.interface("IMyInterface")

All arguments (as well as the return value) of methods for services implemented in Python and defined by r.method(...) are of type json::Value on the RPC layer. In order to avoid having to call a method that is not returning any value by callService<json::Value>, a service method without return value can be explicitly defined using voidMethod(...). This will have to be called with callService<void>, thus is consistent with services implemented in C++. (In contrast to C++, the Python function's return type is not defined before the function is executed and therefore cannot be inferred automatically.)

RPC methods' parameters can be documented by name and description or even name, description and sample value, just as for services implemented in C++. Since parameters are of type json::Value, sample values for these RPC arguments must also be JSON values, or any types that can be extracted as json::Value by the MIRA Python integration layer. This requirement is fullfilled e.g. by primitive types, Python list and dict (using keys of type str only, which is a restriction of the JSON format itself), as the Python toolbox explicitly defines conversion between Python and JSON for those. As a further convenience, any type with a convertObjectToJSON member function is also implicitly converted using that method by the reflection wrapper. Such a method is generically implemented in UnitWrapper.h and automatically added as member function to all types registered using the MIRA_PYTHONCONNECTOR_(NAMED_)TYPE_FOOTER macro defined there too.

Channel access

Units can publish and subscribe to channels that are represented as Channel objects in python. A channel supports different methods to access its data:

Callbacks or calling read() on a channel provides a ChannelRead object that has the following properties:

Using services

To call RPC services one can use the service module. Note that you need to add the MIRADIR folder to the python module search path (PYTHONPATH). The following example calls the RPC method sum() on MyService and prints its result.

import mirapy
from service import Service
s = Service("/MyService")
mirapy.waitForService(s.serviceName)
print s.sum(3,4).get()

The service calls return a RPCFuture that can be used to wait for the return of the call. It supports the following functions:

The module mirapy contains the following global methods:

Note that in contrast to the member methods of the Unit class global methods that take frames or servicenames as parameters do not resolve these names.

Use an own framework with PyQt

You can also use Qt bindings together with a mira pyunit. Therefore you need to have the PySide Qt bindings package installed on your system. To ensure that all handlers are called within the Qt thread you need to set the flag mirapy.Authority.NO_MAIN_THREAD on your unit and call spin from within a Qt timer. The following example shows (after a unit that provides an odometry channel is available) a window with a label that prints the robots current odometry reading.

#!/usr/bin/python
import mirapy
from PySide import QtGui, QtCore
import sys
class MainWindow(QtGui.QMainWindow):
def __init__(self):
super(MainWindow, self).__init__()
self.setGeometry(300, 300, 400, 150)
self.setWindowTitle('OdometryView')
self.label = QtGui.QLabel(self)
self.label.setGeometry(25, 50, 350, 50)
self.unit = mirapy.Unit(mirapy.Authority.NO_MAIN_THREAD)
self.unit.checkin("/", "OdometryListener")
self.unit.subscribe("/robot/Odometry", None, self.onOdometry)
self.timer = QtCore.QBasicTimer()
self.timer.start(100, self)
def onOdometry(self, data):
p = data.Value.Pose
self.label.setText('I am at %0.2fm, %0.2fm, %0.2fdeg' % (p.X, p.Y, p.Phi))
def timerEvent(self, event):
self.unit.spin()
args = ["-d3","-p1234"]
fw = mirapy.Framework(args)
fw.load()
fw.start()
app = QtGui.QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec_()

Using the pyunit tag in config files

One can also instantiate a python unit via the <pyunit> tag from a framework config file. Therefore you need to tell python where to look for your unit scripts, using the <pypath> tag.

<root>
<pypath path="MyPackage:path/to/python/scripts;${FIND path/to/other/stuff}"/>
<pyunit id="SumUnit" class="MyUnit" module="Math">
<Offset>100</Offset>
</pyunit>
</root>

<pypath> optionally adds multiple paths, delimited by ';'. Each individual path is resolved as usual (package names, variables etc.)

The above example assumes that there is a file Math.py in one of the specified python paths, that contains a class MyUnit. It will instantiate an object of this class with the authority id "SumUnit".

Using python from inside miracenter

Within miracenter you can execute python scripts from the Python Editor View. Click on Window->Show View and select the Python Editor View in the Scripts section. The editor starts with a template script that contains the outline of a unit. You can fill in the functionality like in any other unit. If you hit "execute" the script will be interpreted. If you want to change the code just hit "execute" after making the changes. The old unit is destroyed and a new one will be created. The script will be saved inside the workspace configuration when you close miracenter.

Additional data wrapper modules

The MIRA Python toolbox also includes Python wrappers for additional MIRA (and base dependencies') types which may only be required in specific cases. They are generally provided as separate Python modules.

GIT-r395cafa3ce0c9a1b975bfaf187811d93a140ffcb , Generated on Sun Dec 14 2025 03:36:31 for MIRA by   doxygen 1.8.14