Portico FAQ
From Portico
This is a constant work in progress. If you have a specific question that you think should be in here, please contact one of the Developers
Contents |
[edit] Portico General Questions
[edit] How much does Portico cost?
NOTHING!! Portico is an open source HLA RTI implementation, which means that you can download and use it for free.
[edit] How do I download Portico?
[edit] Can I get the source code?
Absolutely! You will need to check it out of the Sourceforge Subersion repository. See here
[edit] How do I install and start Portico?
[edit] What is an LRC?
LRC stands for Local Runtime Component. This is the Portico library itself that is used by individual federates. For every federate you start, Portico creates an LRC. All the LRCs in a federation communicate with one another.
[edit] Using Portico
[edit] How do I write federates for Portico?
[edit] How Much of the HLA API Does Portico Support?
A list of all the RTIambassador and FederateAmbassador methods supported by Portico can be found on the Portico API Status page.
[edit] Portico Networking Questions
[edit] How do Portico Federates Communicate?
Portico federates use a reliable multicast library called JGroups for all inter-federate communication. You can tweat various JGroups configuration options through The RID File.
[edit] My federates won't talk to each other, what is wrong?
There are a couple of potential problems that could cause this. To help diagnose these problems you can turn the JGroups log level up by opening the RID file and setting the option portico.jgroups.loglevel to DEBUG.
Firewall Issues
The first thing to do is check your firewall settings. If the packets are getting lost, federates won't see each other, making them think they are the first members of the federation.
If you see output like this (turn the JGroups log level up first):
DEBUG [main] org.jgroups.protocols.pbcast.GMS: initial_mbrs are [] DEBUG [main] org.jgroups.protocols.pbcast.GMS: no initial members discovered: creating group as first member
You can see that the federates can't talk to one another.
Hostname Issues (common on Linux)
The way JGroups normally determines what network interface to use is to look at the result of hostname and then try and find a corresponding entry in /etc/hosts. It is common for machines to have a hostname of "localhost.localdomain", which is often defined in the /etc/hosts file as 127.0.0.1. If this interface is used by JGroups, the network won't be communicated with.
You can run the hostname program yourself to find out what hostname your machine is using. If you turn up the JGroups logging and check the output, you might see something like this:
DEBUG [main] org.jgroups.protocols.UDP: received CONFIG event: {bind_addr=localhost.localdomain/127.0.0.1}
DEBUG [main] org.jgroups.protocols.UDP: creating sockets and starting threads
DEBUG [main] org.jgroups.protocols.UDP: sockets will use interface 127.0.0.1
This would indicate that the local host address is being used. You might also see entries like this:
WARN [Incoming-6,ExampleFederation,192.168.1.244:50398] org.jgroups.protocols.pbcast.NAKACK: 192.168.1.244:50398] discarded message from non-member 127.0.0.1:32778, my view is [192.168.1.244:50398|0] [192.168.1.244:50398]
This shows that packets are being received from a remote host (192.168.1.244 in this case) but are being ignored because the local machine presumes they are from a non-group member.
There are a couple of ways to fix this problem. The first is to put an entry in the /etc/hosts file for localhost.localdomain with the IP address you want to be used. The second is to change the hostname. If the hostname isn't one that can be found in the hosts file, I've found that JGroups usually finds eth0 (or whatever your other interface is).
You should also try specifying your send/receive interfaces in the RID file (look for them in the JGroups settings). Although I found that didn't solve the problem when localhost.localdomain was returned as a hostname, it might solve your problems if the loopback interface is still being chosen after you change the hostname.
[edit] Configuring Portico
[edit] What is a RID File?
RID stands for "RTI Initialization Data" and it is a configuration file that is read Portico on startup. Users can provide custom configuration data to Portico through the RID file.
To provide RID data to Portico, just place a file called RTI.rid in the directory where you are executing Portico or your federate, or set the value of the RTI_RID_FILE to point to the RID file you want to use.
For more information on using RID files to configure Portico, see "Configuring Portico".
[edit] Portico Structure and Design
[edit] What are communication bindings?
The underlying communications infrastructure used by Portico is entirely abstracted from the internal code. This means that it can easily be swapped out for a different implementations with ease. Currently, two communications bindings are provided with Portico:
- jgroups is the default binding and uses the JGroups reliable multicast library to pass messages between the federates.
- jvm is a binding that can be used when all federates are executing in the same runtime (generally in separate threads). This bindings is like a bit like a shared memory binding, and all raw-I/O is removed, thus providing significant performance gains in situations were all federates can be run in the same execution environment.
You can change the binding in use through The RID File.
[edit] What are plugins?
The Portico framework is extremely flexible. Plugins can easily be written to alter or augment the way Portico behaves. A plugin is a file that contains additional code to perform some new task. To deploy a plugin, you just drop the plugin file into the "RTI_HOME/plugins" directory.
Portico supports 3 types of plugins:
- Message Handlers: Message handers can change the way Portico responds to various requests, or allow it to respond to new types of requests.
- Communications Bindings: Communications bindings define how Portico federates communicate with one another at the network level.
- Daemons: Daemons are background processes that can be started when the RTI starts. The services they provide are undefined and left entirely up to the plugin-developer. For example, a daemon plugin could start an embedded web-server to allow remote web-based access to the state information inside a federate.
For more information on writing plugins, see Writing Plugins.
[edit] Licensing Questions
[edit] Do I have to pay for Portico?
Portico is free software, released under the terms of the CDDL. As such, you don't have to pay any licensing fees or the like. However, there are restrictions on how you can use it.
[edit] Can I use Portico in my Commercial Product?
Yes! As long as you are not altering any of the source code, you are free to use CDDL code in your projects without having to release your source code.
[edit] Do I have to release the source code for my plugin?
Under the terms of the CDDL, as long as your plugin doesn't require any changes to Portico source code, you can choose to distribute it without releasing the source code.
For example, you could choose to write a high-performance communications binding for Portico (that doesn't modify any Portico code) and you could distribute it under any license you wish, without having to release the source code.
In an ideal world, the entire community would be able to benefit from any developments, however we understand commercial realities and believe that the CDDL provides a fair compromise. If you change or alter Portico, you have to give those changes back to the community. If you don’t change the source code, the choice is up to you.
[edit] Contributing to Portico
[edit] Can I contribute to Portico?
YES! See Contributing to Portico for more information.
[edit] Miscellaneous Questions
[edit] Is there anything like DMSO’s RTI Console?
Not at the moment, but a solution is coming.
There used to be a portico console tool, but underlying architectural changes broke it. A new one is on the way!
[edit] Is a C++ interface available?
Yes. A C++ interface for HLA 1.3 is available.
An IEEE1516 C++ interface is planned at some undefined point in the future, but work has not yet begun.
See Portico C++ Inteface for more information.
[edit] Developer Questions
For all developer questions, see the Developer FAQ