Message Documentation

This page contains information about possible request and configure messages to send to the testbed and the possible responses. Furthermore a brief introduction of how to interact with the WiseGroup is given. The WiseGroup is an OMF resource representing one or a set of nodes.

Last but not least a short overview about other messages is given. These messages may be send from nodes of the testbeds without any preceding configure or request message.

WiseGroup Methods and Commands

Methods in this section can be called on any WiseGroup object and will affect the according nodes in the testbed. An optional callback block can be passed to every of these methods.

Hence single nodes as well as set of nodes are represented by a WiseGroup, there is no difference between interacting with a single node or many nodes at the same time. You'll only need to use the appropriate WiseGroup topic and the framework delegates the calls to the nodes in the group.

If you have an instance of a WiseOMF::Client::WiseGroup (e.g. from the WiseOMF::Client::ReservationManager) named group you can call the methods like in the following example:

Example:

group.set_xxx(parameter) { |properties|
  # callback block for method with parameters ...
}

group.yyy { |properties|
  # callback block for method without parameters ...
}

Note: The properties variable in the callback block contains a data structure as described in the following sections. In general all properties have a type field describing the message type. This field could be used to decide what to do with the message.

The Default Callback

Every instance of WiseOMF::Client::WiseGroup can have a default callback handler for handling messages without a matching callback block. This might be useful for catching upstream messages as described in "Upstream Messages". Furthermore some OMF specific messages may occur during the experiment. Whenever it is not possible to call a specific callback block in your experiment, the default callback will be called.

Example:

group.default_callback = lambda { |message|
  # message is an object containing the information of the entire FRCP message
}

Note: Due to the fact that OMF specific messages may have a format different to testbed specific properties, the default callback block will receive the entire message as parameter. Usually this message contains a field properties in which the information described in the following sections may be contained (if the message is from the testbed). The properties field may contain arbitrary data if the message is OMF specific or from another OMF resource than a wisebed_node.

Configuration Methods

This section contains methods that can be used for modifying the state of nodes in a group. In OMF language these methods are used for creating FRCP configure messages. Speaking in programming language words, you can think of these methods as setter methods.

set_image

This method can be used for flashing a binary image onto the nodes.

• Parameter:

  a Base64 encoded binary image

• Callbacks:

  A callback handler for the set_image methods might receive responses as well as progress messages.

  Progress Messages:

  ---
  type: :progress
  requestId: <unique-request-id (Integer)>
  nodeUrn: "<node urn of node sending the progress message>"
  progress: <progress in percent>

  Response Messages:

  ---
  type: :response
  requestId: <unique-request-id (Integer)>
  responses:
  - nodeUrn: "<node urn of node sending this response>"
    response: <Base64 encoded response> 
    statusCode: <the status code between 0 and 100 (progress in percent) or negative if error>
    errorMessage: <optional, if an error occured>
  - <further responses>

set_message

This method can be used to send a message to the nodes.

• Parameter:

  An arbitrary sequence of bytes as Base64 encoded string.

• Callbacks:

  A callback handler receives an ACK or an error message as direct response to the call. Furthermore multiple upstream messages may be send as reaction to the downstream message.

  Response Messages:

  ---
  type: :response
  requestId: <unique-request-id (Integer)>
  responses:
  - nodeUrn: "<node urn of node sending this response>"
    statusCode: <the status code>
    errorMessage: <optional, if an error occured (e.g. node is not connected)>
  - <further responses>

  Upstream Messages:

  ---
  type: :message
  requestId: <unique-request-id (Integer)>
  nodeUrn: "<node urn>"
  timestamp: <a timestamp>
  payload: <a Base64 encoded sequence of bytes>

reset

This method can be used to reset the nodes to their default state. It expects no other parameter than the optional callback.

• Callbacks:

  Response Messages:

  ---
  type: :response
  requestId: <unique-request-id (Integer)>
  responses:
  - nodeUrn: "<node urn of node sending this response>"
    statusCode: <the status code>
    errorMessage: <optional, if an error occured (e.g. node is not connected)>
  - <further responses>

Request Methods

This section contains methods helpful for getting the state of nodes in a group. In OMF language these methods are used for creating FRCP request messages. Speaking in programming language words, you can think of these methods as getter methods with the only difference, that the requested value is not returned directly but in an asynchronous callback.

alive

This method can be used to check whether nodes are alive or not.

• Callbacks:

  Response Messages:

  ---
  type: :response
  requestId: <unique-request-id (Integer)>
  responses:
  - nodeUrn: "<node urn of node sending this response>"
    statusCode: <the status code [0: not alive, 1: alive]>
    errorMessage: <optional, if an error occured (e.g. node is not connected)>
  - <further responses>

connected

This method can be used to check whether nodes are connected or not.

• Callbacks:

  Response Messages:

  ---
  type: :response
  requestId: <unique-request-id (Integer)>
  responses:
  - nodeUrn: "<node urn of node sending this response>"
    statusCode: <the status code [0: not connected, 1: connected]>
    errorMessage: <optional, if an error occured (e.g. node is not connected)>
  - <further responses>

Upstream Messages

In this section we'll describe the format of messages beeing send by the testbed and the nodes in your groups. You'll receive these messages on the group topic of every group containing at least one affected node. Due to the fact that these messages don't have a request id, only the default callback of the affected groups is called.

nodes_attached

This message is send if at least one node is attached.

---
type: :nodes_attached
nodeUrns:
- "<node urn>"
timestamp: <timestamp of this event>
reason: "Some nodes in this group were attached."

nodes_detached

This message is send if at least one node is detached.

---
type: :nodes_detached
nodeUrns:
- "<node urn>"
timestamp: <timestamp of this event>
reason: "Some nodes in this group were detached."

notification

This message is send for notifications comming from the nodes.

---
type: :notification
nodeUrns:
- "<node urn>"
timestamp: <timestamp of this event>
message: "<The notification>"

message

This message is send for messages written by the node on the UART.

---
type: :message
requestId: <unique-request-id (Integer)>
nodeUrn: "<node urn>"
timestamp: <a timestamp>
payload: <a Base64 encoded sequence of bytes>