Skip to content
This repository has been archived by the owner on Aug 25, 2020. It is now read-only.

Release Notes 0.6

Jump to bottom
danbim edited this page Sep 7, 2011 · 3 revisions

API Changes

The 0.6 release of Testbed Runtime implements the new version 2.2 of the WISEBED iWSN APIs. Therefore, clients need to update their implementation, too! The API changes in detail:

Change Nr. Interfaces Affected Short Description Comments
1 Controller, WSN The text message type has been *removed*, using the *binary type as the carrier for everything*. In Java and the BeanShell scripting client this results in the class ```Message``` being the only class generated by importing the WSDL files. There is no more class ```BinaryMessage``` or ```TextMessage``` anymore (cf. below).
2 Controller Both ```receive()``` and ```receiveStatus()``` on the Controller API are permitted to contain an array of messages instead of only one. In Java's Web service stubs which are also used by the wisebed-cmdline-client (aka BeanShell client, aka scripting client) this results in ```Controller.receive(List messages)``` (```Controller.receive(List messages)``` for BeanShell as generics are not support here resp.).
3 Controller A method ```receiveNotification()``` was added to the Controller API, allowing the backend to provide important testbed status/warning messages to the user (note the controller is not mandated to implement this function and can just have a stub that does nothing. This method is, e.g., called by the backend if it drops experiment outputs if it is not able to deliver them in the same rate as sent by the nodes due to, e.g., high network latency or low bandwidth. The best is to always implement this method as to get notified of problems that may affect the experiment outputs.
4 Controller A method ```experimentEnded()``` was added to the Controller API, allowing the backend to inform the controller that it can (if it so wishes) shut down as the experiment/reservation is over and all messages have been delivered to the client.
5 WSN Added a function ```getConfiguration()``` to the Session Management API which returns the URNs of the other Web service endpoints (i.e. RS and SNAA), so the user only needs to know a single endpoint (that of the Session Management API) to use a testbed. This change is not yet included in the experiment scripts of the project but can surely be used in custom clients.

If there are any questions or problems please send an e-mail to the Mailing List.

Changes to Testbed Clients

The most changes to the APIs reflect in the implementation of, e.g., the listen-script shipped with Testbed Runtime. The old version (0.5.5) implemented the Controller API as follows:

...
Controller controller = new Controller() {
  public void receive(Message msg) {
    synchronized(System.out) {
      System.out.print(msg.getTimestamp() + " | " + msg.getSourceNodeId() + " | ");
      if (msg.getTextMessage() != null) {
        String msgString = msg.getTextMessage().getMsg();
        System.out.print(msg.getTextMessage().getMessageLevel() + " | ");
        System.out.println(msgString.endsWith("\n") ? msgString.substring(0, msgString.length()-2) : msgString);
      } else if (msg.getBinaryMessage() != null) {
        System.out.println(StringUtils.toHexString(msg.getBinaryMessage().getBinaryType()) + " | " + StringUtils.toHexString(msg.getBinaryMessage().getBinaryData()));
      }
    }
  }
  public void receiveStatus(RequestStatus status) {
    // nothing to do
  }
};
...

Now, the new version looks like this:

...
Controller controller = new Controller() {
  public void receive(List msgs) {
    for (int i=0; i<msgs.size(); i++) {
      Message msg = (Message) msgs.get(i);
      synchronized(System.out) {

        String text = StringUtils.replaceNonPrintableAsciiCharacters(new String(msg.getBinaryData()));

        System.out.print(msg.getTimestamp() + " | ");
        System.out.print(msg.getSourceNodeId() + " | ");
        System.out.print(text + " | ");
        System.out.print(StringUtils.toHexString(msg.getBinaryData()));
        System.out.println();
      }
    }
  }
  public void receiveStatus(List requestStatuses) {
    // nothing to do
  }
  public void receiveNotification(List msgs) {
    for (int i=0; i<msgs.size(); i++) {
      log.info(msgs.get(i));
    }
  }
  public void experimentEnded() {
    log.info("Experiment ended");
    System.exit(0);
  }
};
...

Several things can be read from these code examples:

  1. Both receive() and receiveStatus() now receive a List instead of a Message resp. a RequestStatus object.
  2. A differentiation between text messages and binary messages is now "missing". This means that the client has to do the interpretation of the binary data himself.
  3. Backend notifications (receiveNotification) should be print to console or some log file so that experimenters get an idea of what may be wrong if something went wrong.
  4. The experimentEnded() function allows to react on the end of an experiment. In the easiest case clients can change their implementations as indicated above or can use the prepared scripts of the experimentation scripts assembly you can get from the Downloads page.

Changes for Testbed Providers

iWSN Configuration

Testbed providers need to update their configuration file of Testbed Runtime's iWSN implementation to get version 0.6 running correctly. The new configuration file for iwsn (in this case taken from UZL's testbed) looks as follows:

...
<applications>
  <application factoryclass="de.uniluebeck.itm.tr.runtime.portalapp.PortalServerFactory" name="Portal">
    <ns3:portalapp>
      <webservice>

        <urnprefix>urn:wisebed:uzl1:</urnprefix>

        <sessionmanagementendpointurl>http://wisebed.itm.uni-luebeck.de:8888/sessions</sessionmanagementendpointurl>
        <wsninstancebaseurl>http://wisebed.itm.uni-luebeck.de:8888/wsn/</wsninstancebaseurl>
        <wisemlfilename>../conf/tr.iwsn-wiseml.xml</wisemlfilename>

        <reservationendpointurl>http://wisebed.itm.uni-luebeck.de:8889/rs</reservationendpointurl>
        <snaaendpointurl>http://wisebed.itm.uni-luebeck.de:8890/snaa</snaaendpointurl>

        <protobufinterface>
          <port>8885</port>
          <ip>0.0.0.0</ip>
        </protobufinterface>

      </webservice>
    </ns3:portalapp>
  </application>
</applications>
...

The only new thing is the XML tag <snaaendpointurl> that points to the SNAA system's endpoint URL. This value is returned if a client calls SessionManagement.getConfiguration().

Federator

The federator implementation has also been updated to work with the new APIs. Because of that, we took out all the not yet up-to-date testbeds from our Federator's configuration. Please contact UZLs team to include your testbed into the federator again after updating your API implementation or installing Testbed Runtime 0.6.

Limiting Message Rate at the Gateways

We experienced problems if an experimenter deployed an application to a node that outputs a lot of messages per second so that the backend could not deliver them in time and the overall system performance went down. Therefore the additional configuration parameter <maximummessagerate> can be given to the device configuration in tr.iwsn-testbed.xml that limits the nodes' message rate:

...
<application factoryclass="de.uniluebeck.itm.tr.runtime.wsnapp.WSNDeviceAppFactory" name="WSNDeviceApp">
  <ns4:wsnDevice>
    <urn>urn:wisebed:uzl1:0x1bb3</urn>
    <type>isense</type>
    <maximummessagerate>50</maximummessagerate>
  </ns4:wsnDevice>
</application>
...

If the gateway drops messages it will send a notification to the Controller.receiveNotification() method so that the user gets notified of this.

Full List of Changes and Bugfixes

A (close to) full list of changes and bugfixes that went into this release can be found here.

Clone this wiki locally