Underwater Networks Handbook

Agents are the basic building blocks of the UnetStack. They exchange messages, provide services and implement protocols. While what is expected from a well-behaved agent is quite demanding, most of the necessary core behaviors are already implemented for you by the UnetAgent base class. All you need to do is to extend it, and add in a little code to teach the agent what you want it to do.

The basic skeleton of a Groovy agent looks like this:

While you don’t strictly need the @Override annotations, it is a good practice to use them whenever you are overriding a method from a superclass. The annotation tells the compiler that this is what you intend, and so if you make a typographical mistake and type in a wrong method name (one that doesn’t exist in the superclass), the compiler will warn you.

If you do not need any of these methods, you can skip the definition as the base class provides default implementations. There are a several other methods that you can override to customize your agent, but these are less commonly needed and so we’ll skip them for now. You’ll come across them later.

It’s best to illustrate with a simple example.

Let’s develop an echo daemon that will respond to each incoming echo request datagram with an echo response datagram containing the same data as the echo-request. We need a way to identify which datagram is an echo request, as we don’t want to be echoing datagrams intended for other agents or for the user. We do this by defining an echo request datagram as any datagram with protocol USER (recall that protocol numbers from USER onwards are available for your own applications to use). We do not want the response to use the same protocol, otherwise our daemon (running on the source node) could get confused and echo the response, which would in turn be echoed again by the destination node’s daemon, ad infinitum. So we use protocol DATA for the echo response datagram, as this protocol is intended for generic application data.

Here’s our daemon:

Let’s walk through the above code:

That’s it!

It’s time for us to test this agent. Create a file called EchoDaemon.groovy in the classes folder and copy the above daemon code into it.

Now start the 2-node network simulation that we have been using as a testbed, and on node B, load the agent:

Our daemon is up and running!

Once the daemon is successfully loaded on node B, we can test it from node A:

We have written our first agent! Was easy, wasn’t it?

If you’re a Java programmer and find the Groovy syntax daunting, you might prefer to write your agents in pure Java (at the expense of verbosity and more steps for testing). This is the equivalent Java code below for the Groovy agent we developed in the last section:

In Java, you’ll first need to compile the Java code. Create a EchoDaemon.java file with the above contents. To compile it, you’ll need to have fjåge and unet-framework jar files on the classpath:

You should now have a EchoDaemon.class file which you copy to the classes folder. To avoid duplicate classes, remember to first delete the EchoDaemon.groovy file!

Finally, you can run the 2-node network simulator and test the agent, just as you did in the previous section.

Agents implement most of their functionality with behaviors.

We have been implicitly using two behaviors so far. The startup() method is called by the UnetAgent base class using a OneShotBehavior , and the processMessage() method is called from a MessageBehavior . While you could have manually added these behaviors, the UnetAgent base class does this for you, because almost all Unet agents require this.

Let’s next look at a use case for explicitly adding other behaviors. Say we wanted our echo daemon to not respond immediately, but after 7 seconds. How would we do that?

We could of course add a delay(7000) in the processMessage() method, but that would be a bad idea. If we did that, the agent would sleep for 7 seconds on receiving a request and not process any request from any other nodes! We want the agent to be responsive while waiting, and so do not want to block execution. Instead, we want a behavior that will occur 7 seconds later — this is precisely what a WakerBehavior does. Here’s our new processMessage() method:

The WakerBehavior that we add is triggered 7000 ms later, and the echo response is sent in that behavior. Simple!

Go ahead and replace the processMessage() method in your EchoDaemon.groovy file and try it! In order to reload the agent, all you need to do on node B is:

And now you can send an echo request from node A as before and see that the response is delayed by 7 seconds.

You could also send a second request during those 7 seconds, and the echo daemon on node B would process that concurrently. You can send 2 echo requests right after each other, and you’ll see the corresponding echo responses 7 seconds later, but right after each other.

We have seen many agents with parameters that you can get/set. If we wanted to make our echo daemon delay configurable, it would be perfect to expose it as a parameter. Let’s do that next.

With the echo daemon loaded on node B, we see that it doesn’t have any configurable parameters by default:

Let’s add a title, description and one delay parameter to our daemon:

Let’s see how the agent looks with parameters. Reload the agent on node B and check its parameters:

We have changed the delay from 7 seconds to 5 seconds. Go ahead and send a echo request from node A and see that you get a response back in 5 seconds!

Most of the agents we have been interacting with, have advertised services, and sometimes, optional capabilities. They also honor requests and publish unsolicited notifications. All of these are quite straightforward to implement, and you can explore some of these features in this blog article on how to implement a simple PHYSICAL service agent (modem driver). We will explore some of these in the next chapter, along with other cool features like finite state machine behaviors and protocol data unit (PDU) codecs.