Skip to content
This repository has been archived by the owner on Sep 21, 2022. It is now read-only.

Experimentation Scripts 0.8

Jump to bottom
danbim edited this page Jul 27, 2012 · 4 revisions

First Steps

  1. Create an Account
    • Sign up here
    • (Bug workaround: If you can't login later change your initial password here)
  2. Get the Client
  3. Set up a Configuration File
    • See detailed instructions below
    • In the following denoted as live.properties
  4. Make a Reservation
    • Choose nodes (eg list all isense nodes)
./wb-list-node-urns live.properties csv isense

* Reserve nodes (eg for for 30 minutes beginning in 10 minutes)

./wb-reserve ../live.properties 30 10 urn:wisebed:uzl1:0xcbe4,urn:wisebed:uzl1:0xcbe5

* Write down the secret reservation key you get
  1. Flash Nodes
    • Flash your image (eg iseraerial-isense.bin)
./wb-flash live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 iseraerial-isense.bin csv urn:wisebed:uzl1:0xcbe4,urn:wisebed:uzl1:0xcbe5
  1. View the Results
    • Get output (from the UART of your nodes) while the experiment is running
./wb-listen live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 csv
  1. Start from Scratch
    • Reset testbed to the state it was before your experiment
./wb-free live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900

Detailed Instructions

Testbed Runtime provides a set of bash-scripts that trigger the execution of various BeanShell scripts by the Scripting Client 0.8. You can download the 0.8 version here. Then, unpack it by running:

tar xvzf tr.experimentation-scripts-0.8.tar.gz

The extracted directory contains the following subdirectories:

bin
lib
scripts

The directory bin contains the executable bash scripts described below, lib contains the Scripting Client 0.8 used to execute the BeanShell scripts and scripts contains the BeanShell scripts that are being passed to the Scripting Client 0.8 upon invocation of one of the bash scripts from the bin directory.

All scripts can be used in a similar way: the first argument is always a property file that contains the actual endpoint URLs of the WISEBED testbed to be used and the users' credentials. Here's an example of such a configuration file:

testbed.snaa.endpointurl  = http://wisebed.itm.uni-luebeck.de:8890/snaa
testbed.rs.endpointurl    = http://wisebed.itm.uni-luebeck.de:8889/rs
testbed.sm.endpointurl    = http://wisebed.itm.uni-luebeck.de:8888/sessions
testbed.urnprefixes       = urn:wisebed:uzl1:

testbed.usernames         = [email protected]
testbed.passwords         = yourpasswordhere

testbed.protobuf.hostname = wisebed.itm.uni-luebeck.de
testbed.protobuf.port     = 8885

The first three lines point to the endpoint URLs of the SNAA, RS and SessionManagement endpoints of the specific testbed on which to conduct experiments. The property testbed.urnprefixes contains the URN prefix which is served by the testbeds' endpoint (note the colon : at the end of the value, e.g. urn:wisebed:uzl1:!). If you are unsure which URN prefix your testbed is serving just check which prefix the individual node URNs have in common. Usually the URN prefix is concatenated with a nodes' MAC address so that, e.g. for a given node URN urn:wisebed:uzl1:0x1234 of a node with MAC address 0x1234 the testbeds' URN prefix is urn:wisebed:uzl1:.

Lines 6 and 7 contain the users' credentials.

The properties testbed.protobuf.hostname and testbed.protobuf.port are optional. They are used by the unofficial protocol buffers based WISEBED API implemented by Testbed Runtime that allows to use the testbed without public IP and being firewalled as all communication happens through a client-initiated bidirectional TCP connection unlike the official APIs. If these properties are set the usage of this unofficial API is tried first and, if this doesn't work, the Web Service-based API is tried.

For Windows Users: If you're running Windows without Cygwin (i.e. you can not execute unix shell scripts) you can use the Alternative Invocation method which is described for every script. Unfortunately, there are no batch scripts until today.

wb-are-nodes-alive

Calls [WSN.areNodesAlive()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#areNodesAlive(java.util.List<java.lang.String>)) to check for a sensor nodes liveness.

Usage

./wb-are-nodes-alive PROPERTIES_FILE SECRET_RESERVATION_KEYS [csv|lines] [NODEURNS]

Example

./wb-are-nodes-alive live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 csv urn:wisebed:uzl1:0xf859,urn:wisebed:uzl1:0xf860

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.listtype=[csv|lines] \
 -Dtestbed.nodeurns=NODEURNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-are-nodes-alive.java

wb-are-nodes-alive-sm

Calls [SessionManagement.areNodesAlive()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/sm/SessionManagement.html#areNodesAlive(java.util.List<java.lang.String>, java.lang.String)) to check for a sensor nodes liveness.

Usage

./wb-are-nodes-alive-sm PROPERTIES_FILE [NODEURNS]

Example

./wb-are-nodes-alive-sm live.properties urn:wisebed:uzl1:0xf859,urn:wisebed:uzl1:0xf860

Alternative Invocation

java \
 -Dtestbed.listtype=[csv|lines] \
 -Dtestbed.nodeurns=NODEURNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-are-nodes-alive-sm.java

wb-destroy-virtual-link

Calls [WSN.destroyVirtualLink()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#destroyVirtualLink(java.lang.String, java.lang.String)) to remove a virtual link.

Usage

./wb-destroy-virtual-link PROPERTIES_FILE SECRET_RESERVATION_KEYS SOURCE_NODE_URN TARGET_NODE_URN [csv|lines]

Example

./wb-destroy-virtual-link live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 urn:wisebed:uzl1:0xf859 urn:wisebed:uzl1:0xf860 csv

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.vlink.from=SOURCE_NODE_URN \
 -Dtestbed.vlink.to=TARGET_NODE_URN \
 -Dtestbed.listtype=[csv|lines] \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-destroy-virtual-link.java

wb-flash

Calls [WSN.flashPrograms()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#flashPrograms(java.util.List<java.lang.String>, java.util.List<java.lang.Integer>, java.util.List<eu.wisebed.api.wsn.Program>)) to reprogram devices.

Usage

./wb-flash PROPERTIES_FILE SECRET_RESERVATION_KEYS IMAGE [lines|csv] [NODEURNS]

Example

./wb-flash live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 iseraerial-isense.bin csv urn:wisebed:uzl1:0xcc3d,urn:wisebed:uzl1:0xcc3e

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.image=IMAGE \
 -Dtestbed.listtype=[lines|csv] \
 -Dtestbed.nodeurns=NODEURNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE
 -f scripts/wb-flash.java

wb-free

Calls [SessionManagement.free()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/sm/SessionManagement.html#free(java.util.List<eu.wisebed.api.sm.SecretReservationKey>)) to "free" the testbed back end from all experiment specific data such as pipeline or virtual link configurations. Sets back the state of the testbed back end to what it was when the experiment (i.e. the reservation time slot) started.

Usage

./wb-free PROPERTIES_FILE SECRET_RESERVATION_KEYS

Example

./wb-free live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-free.java

wb-get-supported-channelhandlers

Calls [WSN.getSupportedChannelHandlers()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#getSupportedChannelHandlers(\)) and pretty-prints the returned data.

Usage

./wb-get-supported-channelhandlers PROPERTIES_FILE SECRET_RESERVATION_KEYS

Example

./wb-get-supported-channelhandlers live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-get-supported-channelhandlers.java

prints the supported channel handlers that can be configured into the backend by calling the set-channel-pipeline script. The name value in the example below corresponds to the value of the factory attribute of the handler tag in the XML configuration file of the set-channel-pipeline script (see above). The configurationOptions values correspond to what can be set as options in the corresponding handler tags.

ChannelHandler {
	name="isense-otap"
	description="The module implements over-the-air-programming (OTAP) functionality to program a set of iSense nodes from coalesenses wirelessly. The nodes must be in single-hop range of the node that is connected to this pipeline. The connected sensor must have iSerAerial functionality enabled while the to-be-programmed devices must be OTAP-capable. Also see https://github.com/itm/netty-handlerstack/wiki/ISense-over-the-air-programming-Protocol."
	configurationOptions={
		key="timeoutMultiplier", description="(short, optional, default=1000)"
		key="maxRerequests", description="(short, optional, default=30)"
		key="timeunit", description="(int, optional, default=MILLISECONDS)"
		key="threadCount", description="(int, optional, default=10)"
		key="deviceTimeout", description="(int, optional, default=160*presenceDetectInterval)"
		key="presenceDetectInterval", description="(int, optional, default=2000)"
	}
}
ChannelHandler {
	name="dlestxetx-framing-encoder"
	description="Wraps an incoming ChannelBuffer with DLE STX (0x10 0x02) and DLE ETX (0x10 0x03) and does byte stuffing inside the ChannelBuffer (i.e. escape every DLE with another DLE). Also see https://github.com/itm/netty-handlerstack/wiki/DLESTXETX-Framing-Decoder-Encoder."
	configurationOptions={}
}
ChannelHandler {
	name="dlestxetx-framing-decoder"
	description="Unwraps a ChannelBuffer instance that is wrapped with DLE STX (0x10 0x02) and DLE ETX (0x10 0x03) and does byte unstuffing (i.e. bytes of value DLE that were escaped with another DLE have the escape character removed. Also See https://github.com/itm/netty-handlerstack/wiki/DLESTXETX-Framing-Decoder-Encoder."
	configurationOptions={}
}
...

wb-list-node-details

Calls [SessionManagement.getNetwork()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/sm/SessionManagement.html#getNetwork(\)), parses the returned WiseML, extracts and prints information about all nodes.

Usage

./wb-list-node-details PROPERTIES_FILE [NODE_TYPES]

Example

./wb-list-node-details live.properties isense,telosb

Alternative Invocation

java \
 -Dtestbed.nodetypes=NODE_TYPES \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-list-node-details.java

wb-list-node-urns

Calls [SessionManagement.getNetwork()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/sm/SessionManagement.html#getNetwork(\)), parses the returned WiseML, extracts and prints all node-urns.

Usage

./wb-list-node-urns PROPERTIES_FILE [csv|lines] [NODE_TYPES]

Example

./wb-list-node-urns live.properties csv isense,telosb

Alternative Invocation

java \
 -Dtestbed.listtype=[csv|lines] \
 -Dtestbed.nodetypes=NODE_TYPES \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-list-node-urns.java

wb-list-reserved-node-details

Calls [WSN.getNetwork()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#getNetwork(\)), parses the returned WiseML, extracts and prints information about all nodes.

Usage

./wb-list-reserved-node-details PROPERTIES_FILE SECRET_RESERVATION_KEY [NODE_TYPES]

Example

./wb-list-reserved-node-details live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 isense,telosb

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.nodetypes=NODE_TYPES \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-list-reserved-node-details.java

wb-list-reserved-node-urns

Calls [WSN.getNetwork()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#getNetwork(\)), parses the returned WiseML, extracts and prints all node-urns.

Usage

./wb-list-reserved-node-urns PROPERTIES_FILE SECRET_RESERVATION_KEY [csv|lines] [NODE_TYPES]

Example

./wb-list-reserved-node-urns live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 csv isense,telosb

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.listtype=[csv|lines] \
 -Dtestbed.nodetypes=NODE_TYPES \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-list-reserved-node-urns.java

wb-listen

Starts a Controller on the local host and connects to the running experiment. Prints out all data and notifications received. If the alternative unofficial protocol buffers based API is used no local Controller Web service is started but the asynchronous responses and node outputs come in through this TCP connection opened by the client.

Usage

./wb-listen PROPERTIES_FILE SECRET_RESERVATION_KEYS [lines|csv]

Example

./wb-listen live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 csv

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.listtype=[lines|csv] \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-listen.java

wb-reserve

Calls [RS.makeReservation()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/rs/RS.html#makeReservation(java.util.List<eu.wisebed.api.rs.SecretAuthenticationKey>, eu.wisebed.api.rs.ConfidentialReservationData)) to make a reservation with the given arguments.

Usage

./wb-reserve PROPERTIES_FILE DURATION_IN_MINUTES [OFFSET_IN_MINUTES] [NODE_URNS]

Example

./wb-reserve ../live.properties 30 10 urn:wisebed:uzl1:0xcbe4

Alternative Invocation

java \
 -Dtestbed.duration=DURATION_IN_MINUTES \
 -Dtestbed.offset=OFFSET_IN_MINUTES \
 -Dtestbed.nodeurns=NODE_URNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-reserve.java

wb-reset

Calls [WSN.resetNodes()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#resetNodes(java.util.List<java.lang.String>)) to reset the nodes.

Usage

./wb-reset PROPERTIES_FILE SECRET_RESERVATION_KEYS [lines|csv] [NODEURNS]

Example

./wb-reset live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 csv urn:wisebed:uzl1:0xf859,urn:wisebed:uzl1:0xf860

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.listtype=[lines|csv] \
 -Dtestbed.nodeurns=NODE_URNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-reset.java

wb-send

Calls [WSN.send()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#send(java.util.List<java.lang.String>, eu.wisebed.api.common.Message)) to send a binary message to the sensor node. Depending on the configuration of the channel pipeline (see Customizing the channel pipeline this data might be changed before being delivered to the sensor nodes UART.

Hint: MESSAGE consists of comma-separated bytes in base_10 (no prefix), base_2 (prefix 0b) or base_16 (prefix 0x)

Usage

./wb-send PROPERTIES_FILE SECRET_RESERVATION_KEYS MESSAGE [csv|lines] [NODEURNS]

Example

./wb-send live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 0x0A,0x1B,0b11001001,40,40,0b11001001,0x1F csv urn:wisebed:uzl1:0xcc3d,urn:wisebed:uzl1:0xcc3e

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.message=MESSAGE \
 -Dtestbed.listtype=[csv|lines] \
 -Dtestbed.nodeurns=NODE_URNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-send.java

wb-set-channel-pipeline

Calls [WSN.setChannelPipeline()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#setChannelPipeline(java.util.List<java.lang.String>, java.util.List<eu.wisebed.api.wsn.ChannelHandlerConfiguration>)) to configure the back ends channel pipeline.

Usage

./wb-set-channel-pipeline PROPERTIES_FILE SECRET_RESERVATION_KEYS CONFIG_FILE [lines|csv] [NODEURNS]

Example

./wb-set-channel-pipeline live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 handlerchain.xml urn:wisebed:uzl1:0xcc3d,urn:wisebed:uzl1:0xcc3e

Alternative Invocation

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.configfile=CONFIG_FILE \
 -Dtestbed.listtype=[lines|csv] \
 -Dtestbed.nodeurns=NODEURNS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-set-channel-pipeline.java

Arguments

The parameter CONFIG_FILE contains an XML description of the protocol stack (i.e. the channel pipeline) that should be set for the individial node. An example of such a configuration can be seen below:

<itm-netty-handlerstack>
    <handler factory="protocoly"/>
    <handler factory="protocolx-encoder">
        <option key="1" value="1"/>
        <option key="2" value="2"/>
    </handler>
    <handler factory="protocolx-decoder">
        <option key="11" value="11"/>
        <option key="22" value="22"/>
    </handler>
</itm-netty-handlerstack>

The order of the <handler>-tags corresponds to the position of the protocol handler in the stack. Please check the netty-handlerstack project for the available handlers or invoke the get-channel-pipeline script.

The parameter NODEURNS can either be 1.) omitted, 2.) may contain a set of comma-separated node URNs or 3.) may contain the string "portal".

  1. If the parameter is omitted the channel pipeline will be set on all reserved node URNs, i.e. each node has the same channel pipeline configuration but each node has its own channel pipeline.
  2. If the parameter contains a set of node URNs only these node URNs will have their channel pipeline configured with the given configuration. Other nodes are left as they currently are.
  3. If the string "portal" is passed as argument there will be one channel pipeline with that configuration on the portal server of the testbed through which the traffic of all nodes will be flowing.

wb-set-virtual-link

Calls [WSN.setVirtualLink()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#setVirtualLink(java.lang.String, java.lang.String, java.lang.String, java.util.List<java.lang.String>, java.util.List<java.lang.String>)) to set a unidirectional virtual link between a source node and a target node.

Usage

./wb-set-virtual-link PROPERTIES_FILE SECRET_RESERVATION_KEYS SOURCE_NODE_URN TARGET_NODE_URN [csv|lines]

Example

./wb-set-virtual-link live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900 urn:wisebed:uzl1:0xf859 urn:wisebed:uzl1:0xf860 lines

Alternative Usage

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -Dtestbed.vlink.from=SOURCE_NODE_URN \
 -Dtestbed.vlink.to=TARGET_NODE_URN \
 -Dtestbed.listtype=[csv|lines] \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-set-virtual-link.java

wb-show-reserved-wiseml

Calls [WSN.getNetwork()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/wsn/WSN.html#getNetwork(\)) and pretty-prints the returned WiseML.

Usage

./show-wiseml PROPERTIES_FILE SECRET_RESERVATION_KEYS

Example

./show-wiseml live.properties urn:wisebed:uzl1:,D2C88AEE416EDD2FD4038BC1252A8900

Alternative Usage

java \
 -Dtestbed.secretreservationkeys=SECRET_RESERVATION_KEYS \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-show-reserved-wiseml.java

wb-show-wiseml

Calls [SessionManagement.getNetwork()](http://wisebed.eu/api/java/current/reference/eu/wisebed/api/sm/SessionManagement.html#getNetwork(\)) and pretty-prints the returned WiseML.

Usage

./wb-show-wiseml PROPERTIES_FILE

Example

./wb-show-wiseml live.properties

Alternative Usage

java \
 -jar lib/tr.scripting-client-0.8-onejar.jar \
 -p PROPERTIES_FILE \
 -f scripts/wb-show-wiseml.java
Clone this wiki locally