Emulation Server

While some of the emulation client applications can be run isolated with a local emulation server of their own, the client / server architecture develops its full usefulness only when all clients share the same emulation server.

Starting the Server

To start the server, envoke the java runtime (JDK or JRE) with option -jar and followed by the file path of the rp2040pio_server.jar emulation server Jar file. Depending on your operating system and version, you may have a file explorer that directly lets you either double-click on the Jar file or right-click on it to start it with a Java runtime. This approach may work, but possibly, you will not see any warnings or confirmation messages that the server emits to its standard output device. Therefore, it is highly recommended to start the server through a terminal:

  • Open a terminal window.
  • Ensure your PATH variables are properly set such that you can envoke the Java runtime or development kit.
  • Use the command cd to go to the directory that contains the file rp2040pio_server.jar.
  • Enter the following command to start an instance of the emulation server:
java -jar rp2040pio_server.jar

You should now see a short confirmation message, including the port number that the server opens for communication with the emulator instance that it just has been created.

$ java -jar jar/rp2040pio_server.jar
Emulation Server Daemon
RP2040 PIO Emulator Version 0.1 / jvm 11.0.11 / 55.0
Copyright © 2021 by Jürgen Reuter, Karlsruhe, Germany.

This software comes with ABSOLUTELY NO WARRANTY;
for details please look at the license file that you
should have received together with this software.
This is free software, and you are welcome to
redistribute it under certain conditions;
for details please look at the license file that you
should have received together with this software.

started emulation server at port 2040

If you try to start another instance of the emulation server in another terminal window, you will get the following message:

failed starting emulation server: Address already in use (Bind
failed)

You will get this message, because the same port can not be shared among different servers. By default, the emulation server uses port 2040 as default, but you are free to use any other port number in the range from 1 to 65535. If on your system, port 2040 is for some reason already in use or, for whatever reason else, you want to use a different port, just envoke the server with the -p option to specify an alternative port:

java -jar rp2040pio_server.jar -p 2041

Note

On most operating systems, for using port numbers in the range 1 to 1023, you will need root or administrator access rights. If you try anyway, you may get the following message:

failed starting emulation server:
Permission denied (Bind failed)

In this case, just choose a different port number above 1023.

Leave the terminal window open while using the emulator (you can minimize the window, but you should not close it). The window may show help warning or confirmation messages. Depending on your operating system, closing the terminal window may also kill the server process, such that the emulation will be shut down.

Shutting Down

When finished with your emulator session, you may safely kill the server process in order to shut down the emulation server. For doing so, on most operating system, just press CTRL-C in the terminal window to stop the server process. After that, you can safely close the terminal window.