Python-driven automation and scripting in Renode with pyrenode3

A user-friendly, well-structured Command Line Interface (CLI) is especially critical in software development tools used for scripting, automation and CI. With our open source Renode simulation framework, Antmicro helps product development teams create, debug, and test multi-node device systems, and Renode’s CLI plays a big part in facilitating just that.

Renode’s CLI, called the Monitor, lets you communicate with Renode and control the simulation using a wide range of built-in features exposed via an API with tab-completion and usage hints for most commands. While simple to use, it follows a custom syntax and does not offer some of the features offered by typical programming languages, such as control statements or loops useful when writing complex scripts.

To bring these and other beneficial features to Renode and improve the overall user experience, Antmicro created pyrenode3, a Python library that allows for interacting with Renode programmatically, granting access to the entire internal API. In this note, we’ll describe the capabilities offered by the initial pyrenode3 implementation and show a simple interactive demo that highlights its features.

Python integration in Renode

As one of the world’s most popular programming languages, Python was a natural candidate for building better interfaces aimed at interacting with Renode. Over the years, the framework has gained several different Python integrations which we often used to implement more advanced functionalities. For many years now, Python can be used from within Renode with an embedded IronPython implementation or via the Robot Framework often used for testing with Renode, which is also written in Python and can be extended using Python scripts.

But the real deal is using Python to instrument Renode from outside - we call this integration pyrenode following a common Python convention. The original pyrenode implementation was developed some years ago in two versions: one based on telnet connections, passing data to the Renode Monitor via sockets and another based on Robot keywords and a RPC mechanism. The latter was heavily used in Google Colabs that we ship for Renodepedia, as can be seen for example here, as it was more robust and easier to use. However, it was also limited to the strictly defined API and ultimately relied on too many abstraction levels to make it comfortable to use.

The newest, third incarnation of pyrenode is much more advanced and complex than the previous two, bringing significant improvements in terms of features but also user experience. To ensure a smooth transition, it was released in a separate repository set to replace the previous version(s) which will eventually be deprecated.

Introducing pyrenode3

In its core, pyrenode3 is a Python library that can be used interactively like Monitor or non-interactively like a Renode script (RESC). Internally, it uses the Python.NET package for communication between C# and Python. It enables direct access to Renode classes, methods, and more, serving as a replacement for telnet and Robot keywords used in the previous versions.

The new features brought by pyrenode3 include autocompletion for methods, machines, and peripherals, for example e.machine0.sysbus.WriteDoubleWord can be written entirely using tab completions.

The built-in Monitor interface in Renode is limited to a few data types, mainly strings, numbers and building blocks for simulation. As the Monitor would not allow you to call a function accepting complex objects as parameters, we had to adapt the internal API to expose the functionality we needed. With the Python API, we have access to the entire code structure, including chained calls and nested objects. For example, property fields such as e.machine0.ElapsedVirtualTime.TimeElapsed.TotalSeconds can now be accessed by users with no additional effort. Previously you’d need to call machine ElapsedVirtualTime and then find the value that interested you in the broader output printed by this method.

For frequently used Renode classes, we created wrappers that allow for easy access to commonly used functionalities with helpers (e.g. load_repl). They also help us hide implementation details - for example they simplify the structure of emulation elements and make getting machines with e.machine_name and accessing peripherals with e.machine_name.sysbus.path.to.some_peripheral possible. Otherwise, instead of e.hifive1 (object-oriented notation) we’d need to write e.machines[‘hifive1’] (using a dictionary notation), and hifive1 would not have been autocompleted.

Pyrenode3 uses bpython as the default Python interpreter for the interactive mode, however that can be replaced with any other interpreter. Support for autocompletions in non-wrapped classes was merged into bpython’s repository and will likely be a part of its release.

Pyrenode3 in practice

We’ve prepared a simple demo that you can try on your local machine by running the following:

wget https://builds.renode.io/renode-latest.pkg.tar.xz
wget https://raw.githubusercontent.com/antmicro/pyrenode3/d8a78b01f8b24029297b118644cc2af2a6760cec/examples/stm32l072-shell.py
export PYRENODE_ARCH_PKG=`pwd`/renode-latest.pkg.tar.xz
bpython -i stm32l072-shell.py

This script will spawn a simple setup with STM32L072 running the Zephyr Shell that you can interact with:

If you’re interested in more complex multi-node scenarios, take a look at another example with Fomu and SiFive HiFive Unleashed.

Python-driven automation in Renode

Apart from the significant improvements pyrenode3 brings to Renode’s scripting and automation capabilities, it can also be used to integrate Renode into larger Python programs as a library. We are currently working on updating the RenodeRuntime in Kenning, Antmicro’s open source tool for optimizing and deploying edge AI solutions, to use pyrenode3. Another exciting work-in-progress integration is enabling the Visual System Designer to act as Renode’s UI.

The pyrenode3 development, introduced as part of the EU-funded TRISTAN project, offers a myriad of further possibilities for extending Renode into various new use cases.

If you’re interested in using Renode in your project that requires complex scripting, automation and CI, don’t hesitate to contact us at contact@antmicro.com to learn more about pyrenode3 and other Python integrations available in Renode.