1# Renode 2 3Copyright (c) 2010-2025 [Antmicro](https://www.antmicro.com) 4 5[](https://opensource.antmicro.com/projects/renode) 6 7## What is Renode? 8 9Renode was created by Antmicro as a virtual development tool for multi-node embedded networks (both wired and wireless) and is intended to enable a scalable workflow for creating effective, tested and secure IoT systems. 10 11With Renode, developing, testing, debugging and simulating unmodified software for IoT devices is fast, cost-effective and reliable. 12 13Supported architectures include: 14 15* ARMv7 and ARMv8 Cortex-A, Cortex-R and Cortex-M 16* x86 and x86_64 17* RISC-V 18* SPARC 19* POWER 20* Xtensa 21 22## Why use Renode? 23 24Renode was created based on many years of experience with the development of software for embedded systems - both for gateways, on-board computers, as well as sensor nodes and microcontrollers. 25 26Testing and developing physical embedded systems is difficult due to poor reproducibility and lack of insight into the current state of a system, especially in multi-node scenarios. 27 28Renode addresses this issue by letting you run unmodified binaries identical to the ones you would normally flash onto their target hardware on a virtual board or system of boards. 29 30One important aspect of the tool is that it simulates not only CPUs but entire SoCs (e.g., heterogeneous multicore SoCs and various peripherals) as well as the wired or wireless connections between them, allowing users to address complex scenarios and test real production software. 31 32## Installation 33 34### Available builds and releases 35 36#### Nightly builds 37 38Nightly builds of Renode for all systems are available at [builds.renode.io](https://builds.renode.io). 39 40The latest builds are always available as `renode-latest.*` packages. 41The following packages formats are available: 42* [`renode-latest.linux-portable-dotnet.tar.gz`](https://builds.renode.io/renode-latest.linux-portable-dotnet.tar.gz) - portable Linux package, embeds dotnet runtime 43* [`renode-latest.linux-portable.tar.gz`](https://builds.renode.io/renode-latest.linux-portable.tar.gz) - portable Linux package, embeds Mono runtime 44* [`renode-latest.linux-dotnet.tar.gz`](https://builds.renode.io/renode-latest.linux-dotnet.tar.gz) - Linux prebuilt archive, requires dotnet installed on host 45* [`renode-latest.pkg.tar.xz`](https://builds.renode.io/renode-latest.pkg.tar.xz) - Arch Linux package 46* [`renode-latest.x86_64.rpm`](https://builds.renode.io/renode-latest.x86_64.rpm) - Red Hat / Fedora package 47* [`renode-latest.deb`](https://builds.renode.io/renode-latest.deb) - Debian-based distribution package 48* [`renode-latest.dmg`](https://builds.renode.io/renode-latest.dmg) - macOS package 49* [`renode-latest.zip`](https://builds.renode.io/renode-latest.zip) - Windows portable package, without installer 50* [`renode-latest.msi`](https://builds.renode.io/renode-latest.msi) - Windows installer 51* [`renode-latest.tar.xz`](https://builds.renode.io/renode-latest.tar.xz) - Renode sources 52 53#### Stable releases 54 55Stable, numbered releases and their release notes are available in the [Releases section](https://github.com/renode/renode/releases) on GitHub. 56 57### Using the Linux portable release 58 59If you are a Linux user, the easiest way to use Renode is to download the latest `linux-portable` from [the releases section](https://github.com/renode/renode/releases/latest) and unpack it using: 60 61``` 62mkdir renode_portable 63wget https://builds.renode.io/renode-latest.linux-portable.tar.gz 64tar xf renode-latest.linux-portable.tar.gz -C renode_portable --strip-components=1 65``` 66 67To use it from any location, enter the created directory and add it to the system path: 68 69``` 70cd renode_portable 71export PATH="`pwd`:$PATH" 72``` 73 74Please note that the portable package requires GTK2 to be available on the host to run with the UI enabled. 75 76Follow the [Additional Prerequisites](#additional-prerequisites-for-robot-framework-testing) section if you wish to use Robot Framework for testing. 77Otherwise, proceed to the 'Running Renode' section. 78 79### Installing dependencies 80 81#### Mono/dotnet 82 83Renode requires Mono >= 5.20 (Linux, macOS) or .NET Framework >= 4.7 (Windows). 84On all systems, you can also use dotnet >= 6.0. 85 86##### Linux 87 88To install dotnet on Linux, follow [the official installation guide](https://learn.microsoft.com/en-us/dotnet/core/install/linux). 89 90Alternatively, install the `mono-complete` package as per the installation instructions for various Linux distributions you can find on [the Mono project website](https://www.mono-project.com/download/stable/#download-lin). 91 92##### macOS 93 94To install dotnet on macOS, follow [the official installation guide](https://learn.microsoft.com/en-us/dotnet/core/install/macos). 95 96Alternatively, for Mono-based setups, you can download the Mono package directly from [the Mono project website](https://download.mono-project.com/archive/mdk-latest-stable.pkg). 97 98##### Windows 99 100To install modern dotnet (as opposed to .NET Framework) on Windows, follow [the official installation guide](https://learn.microsoft.com/en-us/dotnet/core/install/windows). 101The **.NET SDK** includes runtime, so you will be able to build and run Renode. 102 103#### Other dependencies (Linux only) 104 105On Ubuntu 20.04, you can install the remaining dependencies with the following command: 106 107``` 108sudo apt-get install policykit-1 libgtk2.0-0 screen uml-utilities gtk-sharp2 libc6-dev libicu-dev gcc python3 python3-pip 109``` 110 111If you are running a different distribution, you will need to install an analogous list of packages using your package manager; note that the package names may differ slightly. 112 113### Installing from packages 114 115Go to [the releases section](https://github.com/renode/renode/releases/latest) of this repository and download an appropriate package for your system. 116 117#### Linux 118 119Install Renode with your preferred package manager using the provided `*.deb`, `*.rpm` or `*.pkg.tar.xz` packages. 120 121#### macOS 122 123Use the provided `*.dmg` as normal. 124Additionally, to use Renode from the command line on macOS, create appropriate aliases by adding `alias renode='mono /Applications/Renode.app/Contents/MacOS/bin/Renode.exe'` and `alias renode-test='/Applications/Renode.app/Contents/MacOS/tests/renode-test'` to your `.bashrc` or `.zshrc` file, depending on the shell you're using. 125 126#### Windows 127 128Install Renode from the provided `*.msi` file. The installer will allow you to add icons to your Desktop and/or Start Menu and an entry to your PATH. 129 130### Additional prerequisites 131 132#### Robot Framework testing 133 134To write and run test cases, Renode integrates with the Robot testing framework. 135This requires you to install Python 3 (on Windows, you will also need Cygwin - see [the advanced installation instructions](https://renode.readthedocs.io/en/latest/advanced/building_from_sources.html#windows)) with `pip` (note that the relevant package may be called `python-pip` or `python3-pip` on Linux). 136 137Once you have Python 3 and `pip`, install additional modules: 138 139``` 140python3 -m pip install -r tests/requirements.txt 141``` 142 143#### Other tools 144 145Additionally, each of the tools in the `/tools` subdirectory may contain a `requirements.txt` file separate from Renode's requirements. 146 147Install them in your virtual environment with `pip install -r requirements.txt`. 148 149### Building from source 150 151For information on building Renode from source, see [the documentation](https://renode.readthedocs.io/en/latest/advanced/building_from_sources.html). 152 153## Running Renode 154 155After following the instructions above on installation from a package, you should have the `renode` command available system-wide: 156 157``` 158renode [flags] [file] 159``` 160 161If you built it from source, navigate to the relevant directory and use: 162 163``` 164./renode [flags] [file] 165``` 166 167The optional `[file]` argument allows you to provide the path to a script to be run on startup. 168 169The script allows several optional flags, the most useful of which are presented below: 170 171``` 172-p Remove steering codes (e.g., colours) from output 173-P INT32 Instead of opening a window, listen for Monitor commands on the specified port 174-e COMMAND Execute command on startup (executed after the optional script). May be used multiple times 175--console Run the Monitor in the console instead of a separate window 176--disable-gui Disable XWT GUI support. It automatically sets HideMonitor 177--hide-monitor Do not show the Monitor window 178--hide-log Do not show log messages in console 179--hide-analyzers Do not show analyzers 180-v Print version and exit 181-h Display help and usage information 182``` 183 184Renode can be run on Windows systems with a similar set of optional flags. 185 186### Sample scenario 187 188Below, you can see a piece of firmware running on simulated hardware. 189The Renode Monitor is visible alongside an analyzer window displaying UART output and logger. 190For more information about this particular setup, see [its dedicated repository](https://github.com/antmicro/renode-tesla-roadster-simulation). 191 192 193 194### Alternative ways for running Renode on Linux 195 196#### renode-run 197 198`renode-run` is a Python script that downloads and runs Renode, and lets you easily run demos available in [Renodepedia](https://zephyr-dashboard.renode.io/renodepedia/) as well as local ELF files. 199Go to [the repository](https://github.com/antmicro/renode-run) for usage instructions. 200 201`renode-run` relies on a portable package and its main advantage is the ease of updating Renode to the latest nightly build using a single command. 202 203#### pyrenode3 204 205`pyrenode3` is a A Python library for interacting with Renode programmatically. 206Go to [the repository](https://github.com/antmicro/pyrenode3) for usage instructions. 207 208#### Running Renode in a Docker container 209 210If you want to run Renode in Docker, you can use prebuilt images available on [Docker Hub](https://hub.docker.com/r/antmicro/renode). 211 212To start Renode in interactive mode on Linux, assuming you have Docker installed in your system, run one of the following: 213 214* For the latest numbered version build: 215 ``` 216 docker run -ti -e DISPLAY -v $XAUTHORITY:/home/developer/.Xauthority --net=host antmicro/renode:latest 217 ``` 218* For a nightly mono build: 219 ``` 220 docker run -ti -e DISPLAY -v $XAUTHORITY:/home/developer/.Xauthority --net=host antmicro/renode:nightly 221 ``` 222* For a nightly dotnet build: 223 ``` 224 docker run -ti -e DISPLAY -v $XAUTHORITY:/home/developer/.Xauthority --net=host antmicro/renode:nightly-dotnet 225 ``` 226 227This will display the Renode Monitor window. 228Alternatively, you can provide your custom command at the end of the line above. 229 230To run the image in console mode without X server passthrough, run: 231 232``` 233docker run -ti antmicro/renode bash 234``` 235 236You can add more `-v` switches to the command to mount your own directories. 237 238For more information and the underlying Dockerfile, visit the [repository on GitHub](https://github.com/renode/renode-docker). 239 240## Documentation 241 242Documentation is available on [Read the Docs](https://renode.readthedocs.io). 243 244## License & contributions 245 246Renode is released under the permissive MIT license. 247For details, see the [LICENSE](LICENSE) file. 248 249We're happy to accept bug reports, feature requests, and contributions via GitHub pull requests / issues. 250For details, see the [CONTRIBUTING.md](CONTRIBUTING.md) file. 251 252## Commercial support 253 254Commercial support for Renode is provided by [Antmicro](https://antmicro.com), a company specializing in helping its clients to adopt new embedded technologies and modern development methodologies. 255 256Antmicro created and maintains the Renode Framework and related tooling and is happy to provide services such as adding new platforms, integrations, plugins, and tools. 257 258To inquire about our services, contact us at [support@renode.io](mailto:support@renode.io). 259
