-
Notifications
You must be signed in to change notification settings - Fork 1
Customizing the channel pipeline
The WISEBED iWSN API contains an optional method to configure message preprocessing in the testbed backend. The method WSN.setChannelPipeline() allows to configure a completely custom protocol stack (the "channel pipeline") at runtime of an experiment. A channel pipeline consists of an ordered list (i.e. a protocol stack) of channel handlers that may create, modify and remove messages inside a pipeline which is connected to an individual sensor node. This allows both simple decoders and encoders as well as more complex actively acting handlers (such as handlers for executing over-the-air programming (OTAP)).
The method WSN.getSupportedChannelHandlers() provides the user with a possibility to find out which channel handlers are supported and how they must be configured (see below).
The implementation of this concept in Testbed Runtime is based on the JBoss Netty asynchronous event-driven network application framework. All protocols are implemented as reusable components inside the netty-handlerstack project.
By setting an empty channel pipeline no preprocessing is done in the testbeds backend. All data that is being written to the serial connection by the sensor node is directly sent to the testbed client application (i.e. the user) as is.
To remove all handlers from the channel pipeline you can call the set-channel-pipeline script from the Experimentation Scripts 0.8 as follows:
./set-channel-pipeline $PROPERTIES_FILE $RESERVATION_KEY empty.xml
where the file empty.xml contains the following:
<itm-netty-handlerstack />
The default of behaviour of Testbed Runtime at the time of writing this is to have deframing of packets activated for the iSense framing (DLE STX ... DLE ETX) for every sensor node. In a future version it is planned to have it deactivated (i.e. start with an empty channel pipeline) for every node by default.
If a sensor node application writes a sequence of bytes (say 0x27 0x48 0x58) to the serial connection the sensor nodes operating system will typically wrap these bytes with a framing. In case of an iSense node for example it will wrap the bytes with DLE STX ... DLE ETX (where ... is the actual packet, DLE is actually 0x10, STX is 0x02 and ETX is 0x03, see this for a more detailed explanation) before writing it to the serial connection. The testbed backend now will read the following byte sequence from the devices' input stream:
DLE STX 0x27 0x48 0x58 DLE ETX
The testbed backend can now be configured to preprocess this data by so that the framing is being removed. Without the framing the data received by the client application corresponds to one packet that was being written by the sensor node application. So, if you want to configure packet preprocessing you can call the WSN.setChannelPipeline() method to configure the channel pipeline. E.g., to add a decoder that unwraps packets (wrapped with DLE STX ... DLE ETX) you can run the set-channel-pipeline script from the Experimentation Scripts 0.8 as follows:
./set-channel-pipeline $PROPERTIES_FILE $RESERVATION_KEY dlestxetx.xml
where the file dlestxetx.xml contains the following:
<itm-netty-handlerstack>
<handler factory="dlestxetx-framing" />
</itm-netty-handlerstack>
You can retrieve the list of supported channel handlers along with a description of their functionality and the configuration parameters supported/mandatory by invoking the method WSN.getSupportedChannelHandlers(). Using the get-supported-channelhandlers script of the Experimentation Scripts 0.8 assembly you would run e.g.:
./get-supported-channelhandlers $PROPERTIES_FILE $RESERVATION_KEY
which results in the following output (as of the time writing this):
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="iseraerial-packet"
description=""
configurationOptions={}
}
ChannelHandler {
name="iseraerial-packet-encoder"
description="The protocol encoder implements the iSerAerial protocol used by the iSense sensor nodes from coalesenses. The protocol is used on the serial interface between a PC and a sensor node. Any iSerAerial packet sent to the sensor node will be transmitted via the node's radio interface. Any packet received by the node via the radio interface is sent via the serial interface to the PC. Also see https://github.com/itm/netty-handlerstack/wiki/ISerAerial-Protocol-Decoder-Encoder."
configurationOptions={}
}
ChannelHandler {
name="isense-packet-downstream-decoder"
description="Decodes a downstream ChannelBuffer packet to an de.uniluebeck.itm.netty.handlerstack.isense.ISensePacketinstance. An ISensePacket is a simple wrapper that exposes a packet as a pair of packet type (first byte of the packet) and packet payload (remaining bytes of the packet) and is used internally in various handlers. Also see https://github.com/itm/netty-handlerstack/wiki/ISense-Framing-Decoder-Encoder."
configurationOptions={}
}
ChannelHandler {
name="length-field-prepender"
description="An encoder that prepends the length of the message. The length value is prepended as a binary form. It is encoded in either big endian or little endian depending on the default ByteOrder of the current ChannelBufferFactory. See http://docs.jboss.org/netty/3.2/api/org/jboss/netty/handler/codec/frame/LengthFieldPrepender.html"
configurationOptions={
key="lengthFieldLength", description="(int) the length of the prepended length field. Only 1, 2, 3, 4, and 8 are allowed."
key="lengthIncludesLengthFieldLength", description="(boolean) if true, the length of the prepended length field is added to the value of the prepended length field."
}
}
ChannelHandler {
name="isense-packet"
description=""
configurationOptions={}
}
ChannelHandler {
name="isense-packet-upstream-encoder"
description="Encodes an upstream packet of type de.uniluebeck.itm.netty.handlerstack.isense.ISensePacket to a ChannelBuffer instance. An ISensePacket is a simple wrapper that exposes a packet as a pair of packet type (first byte of the packet) and packet payload (remaining bytes of the packet) and is used internally in various handlers. Also see https://github.com/itm/netty-handlerstack/wiki/ISense-Framing-Decoder-Encoder."
configurationOptions={}
}
ChannelHandler {
name="length-field-based-frame-decoder"
description="A decoder that splits the received ChannelBuffers dynamically by the value of the length field in the message. See http://docs.jboss.org/netty/3.2/api/org/jboss/netty/handler/codec/frame/LengthFieldBasedFrameDecoder.html."
configurationOptions={
key="lengthAdjustment", description="(int, optional, default=0) the compensation value to add to the value of the length field"
key="initialBytesToStrip", description="(int, optional, default=0) the number of first bytes to strip out from the decoded frame"
key="lengthFieldLength", description="(int) the length of the length field"
key="lengthFieldOffset", description="(int) the offset of the length field"
key="maxFrameLength", description="(int) the maximum length of the frame. If the length of the frame is greater than this value, TooLongFrameException will be thrown."
}
}
ChannelHandler {
name="dlestxetx-framing"
description="Both dlestxetx-framing-decoder and dlestxetx-framing-encoder. Also see https://github.com/itm/netty-handlerstack/wiki/DLESTXETX-Framing-Decoder-Encoder."
configurationOptions={}
}
ChannelHandler {
name="discard"
description="Discards upstream and downstream messages"
configurationOptions={
key="discardUpstream", description="(optional, boolean, default=true) if true all upstream messages are discarded"
key="discardDownstream", description="(optional, boolean, default=true) if true all downstream messages are discarded"
}
}
ChannelHandler {
name="iseraerial-packet-decoder"
description="The protocol decoder implements the iSerAerial protocol used by the iSense sensor nodes from coalesenses. The protocol is used on the serial interface between a PC and a sensor node. Any iSerAerial packet sent to the sensor node will be transmitted via the node's radio interface. Any packet received by the node via the radio interface is sent via the serial interface to the PC. Also see https://github.com/itm/netty-handlerstack/wiki/ISerAerial-Protocol-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={}
}
ChannelHandler {
name="isense-packet-encoder"
description="Encodes a downstream packet of type de.uniluebeck.itm.netty.handlerstack.isense.ISensePacket to a ChannelBuffer instance. An ISensePacket is a simple wrapper that exposes a packet as a pair of packet type (first byte of the packet) and packet payload (remaining bytes of the packet) and is used internally in various handlers. Also see https://github.com/itm/netty-handlerstack/wiki/ISense-Framing-Decoder-Encoder."
configurationOptions={}
}
ChannelHandler {
name="logging-handler"
description="A handler that logs packets passing through using a SLF4J logger."
configurationOptions={}
}
ChannelHandler {
name="fixed-length-frame-decoder"
description="A decoder that splits the received ChannelBuffers into a fixed number of bytes. See http://docs.jboss.org/netty/3.2/api/org/jboss/netty/handler/codec/frame/FixedLengthFrameDecoder.html."
configurationOptions={
key="frameLength", description="(int) the number of bytes of an individual frame"
}
}
ChannelHandler {
name="isense-ishell-interpreter"
description="The purpose of this module is to enable controlling the behavior of iSense sensor nodes from coalesenses that are attached, e.g. via a serial connection to a PC. Currently it is only possible to set the channel used by the wireless interface. Also see: https://github.com/itm/netty-handlerstack/wiki/ISense-iShell-Interpreter."
configurationOptions={}
}
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="base64-decoder"
description="Decodes a Base64-encoded ChannelBuffer or US-ASCII String into a ChannelBuffer. Seehttp://docs.jboss.org/netty/3.2/api/org/jboss/netty/handler/codec/base64/Base64Decoder.html."
configurationOptions={}
}
ChannelHandler {
name="base64-encoder"
description="Encodes a ChannelBuffer into a Base64-encoded ChannelBuffer. See http://docs.jboss.org/netty/3.2/api/org/jboss/netty/handler/codec/base64/Base64Encoder.html."
configurationOptions={
key="breakLines", description="(boolean)"
}
}
ChannelHandler {
name="isense-packet-decoder"
description="Decodes an upstream ChannelBuffer packet to an de.uniluebeck.itm.netty.handlerstack.isense.ISensePacketinstance. An ISensePacket is a simple wrapper that exposes a packet as a pair of packet type (first byte of the packet) and packet payload (remaining bytes of the packet) and is used internally in various handlers. Also see https://github.com/itm/netty-handlerstack/wiki/ISense-Framing-Decoder-Encoder."
configurationOptions={}
}
Testbed Runtime includes all protocols and handlers registered in the ProtocolCollection class of the netty-handlerstack project. If you need additional handlers, experience issue in the existing handlers, search for additional documentation or just want to check out how they work please go to the netty-handlerstack project homepage.