libowl 1.2

data/lib/libowl/client_world_model.rb

@@ -0,0 +1,243 @@
+################################################################################
+#This file defines the ClientWorldModel class, an object that connects to an
+#Owl world model, simplifying requesting and handling data. This class does not
+#keep a threaded connection open as in the ClientWorldConnection so message
+#handling must be scheduled by the client.
+#
+# Copyright (c) 2013 Bernhard Firner
+# All rights reserved.
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
+# or visit http://www.gnu.org/licenses/gpl-2.0.html
+#
+################################################################################
+
+require 'socket'
+require 'libowl/message_constants.rb'
+require 'libowl/buffer_manip.rb'
+require 'libowl/wm_data.rb'
+require 'libowl/transient_request.rb'
+
+##
+#This class abstracts the network details of connecting to a World Model.
+#However, this class does not use a thread to handle networking in the
+#background as in the ClientWorldConnection class, so handleMessage must
+#be called manually. If threads are available then the ClientWorldConnection
+#class is simpler to use.
+class ClientWorldModel
+  attr_accessor :alias_to_attr_name, :alias_to_origin_name
+  attr_reader :connected
+  @alias_to_attr_name
+  @alias_to_origin_name
+  @connected
+
+  @data_callback
+  @uri_response_callback
+
+  def initialize(host, port, data_callback = nil, uri_response_callback = nil)
+    @connected = false
+    @host = host
+    @port = port
+    @socket = TCPSocket.open(host, port)
+    handshake = ""
+    ver_string = "GRAIL client protocol"
+    #The handshake is the length of the message, the protocol string, and the version (0).
+    handshake << [ver_string.length].pack('N') << ver_string << "\x00\x00"
+    #Send a handshake and then receive one
+    @socket.send(handshake, 0)
+    inshake = @socket.recvfrom(handshake.length)[0]
+    while (inshake.length < handshake.length)
+      #puts "Waiting for #{handshake.length - inshake.length} byte more of handshake."
+      inshake += @socket.recvfrom(handshake.length - inshake.length)[0]
+    end
+
+    @connected = true
+    for i in 1..handshake.length
+      if handshake[i] != inshake[i]
+        puts "Handshake failure!"
+        puts "For byte i we sent #{handshake[i]} but got #{inshake[i]}"
+        @connected = false
+      end
+    end
+
+    @alias_to_attr_name = {}
+    @alias_to_origin_name = {}
+
+    @data_callback = data_callback
+    @uri_response_callback = uri_response_callback
+  end
+
+  def close()
+    @socket.close()
+    @connected = false
+  end
+
+  #Handle a message of currently unknown type
+  def handleMessage()
+    #puts "Handling message..."
+    #Get the message length as n unsigned integer
+    inlen = (@socket.recvfrom(4)[0]).unpack('N')[0]
+    inbuff = @socket.recvfrom(inlen)[0]
+    #Keep reading until the entire packet is read
+    #TODO This can block forever if a communication error occurs.
+    while (inbuff.length < inlen) 
+      inbuff += @socket.recvfrom(inlen-inbuff.length)[0]
+    end
+    #Byte that indicates message type
+    control = inbuff.unpack('C')[0]
+    if control == ATTRIBUTE_ALIAS
+      decodeAttributeAlias(inbuff[1, inbuff.length - 1])
+    elsif control == ORIGIN_ALIAS
+      decodeOriginAlias(inbuff[1, inbuff.length - 1])
+    elsif control == REQUEST_COMPLETE
+      ticket = decodeTicketMessage(inbuff[1, inbuff.length-1])
+      #puts "World Model completed request for ticket #{ticket}"
+    elsif control == DATA_RESPONSE
+      if (@data_callback != nil)
+        @data_callback.call(decodeDataResponse(inbuff[1, inbuff.length - 1]))
+      end
+    elsif control == URI_RESPONSE
+      if (@uri_response_callback != nil)
+        @uri_response_callback.call(decodeURIResponse(inbuff[1, inbuff.length - 1]))
+      end
+    end
+    #puts "processed message with id #{control}"
+    return control
+  end
+
+  #Decode attribute alias message
+  def decodeAttributeAlias(inbuff)
+    num_aliases = inbuff.unpack('N')[0]
+    rest = inbuff[4, inbuff.length - 1]
+    for i in 1..num_aliases do
+      attr_alias = rest.unpack('N')[0]
+      name, rest = splitURIFromRest(rest[4, rest.length - 1])
+      #Assign this name to the given alias
+      @alias_to_attr_name[attr_alias] = name
+    end
+  end
+
+  #Decode origin alias message
+  def decodeOriginAlias(inbuff)
+    num_aliases = inbuff.unpack('N')[0]
+    rest = inbuff[4, inbuff.length - 1]
+    for i in 1..num_aliases do
+      origin_alias = rest.unpack('N')[0]
+      name, rest = splitURIFromRest(rest[4, rest.length - 1])
+      #Assign this name to the given alias
+      @alias_to_origin_name[origin_alias] = name
+    end
+  end
+
+  #Decode a ticket message or a request complete message.
+  def decodeTicketMessage(inbuff)
+    return inbuff.unpack('N')[0]
+  end
+
+  def decodeURIResponse(inbuff)
+    uris = []
+    if (inbuff != nil)
+      rest = inbuff
+      while (rest.length > 4)
+        name, rest = splitURIFromRest(rest)
+        uris.push(name)
+      end
+    end
+    return uris
+  end
+
+  def decodeDataResponse(inbuff)
+    attributes = []
+    object_uri, rest = splitURIFromRest(inbuff)
+    ticket = rest.unpack('N')[0]
+    total_attributes = rest[4, rest.length - 1].unpack('N')[0]
+    rest = rest[8, rest.length]
+    #puts "Decoding #{total_attributes} attributes"
+    for i in 1..total_attributes do
+      name_alias = rest.unpack('N')[0]
+      creation_date = unpackuint64(rest[4, rest.length - 1])
+      expiration_date = unpackuint64(rest[12, rest.length - 1])
+      origin_alias = rest[20, rest.length - 1].unpack('N')[0]
+      data_len = rest[24, rest.length - 1].unpack('N')[0]
+      data = rest[28, data_len]
+      rest = rest[28+data_len, rest.length - 1]
+      attributes.push(WMAttribute.new(@alias_to_attr_name[name_alias], data, creation_date, expiration_date, @alias_to_origin_name[origin_alias]))
+    end
+    return WMData.new(object_uri, attributes, ticket)
+  end
+
+  def sendSnapshotRequest(name_pattern, attribute_patterns, ticket, start_time = 0, stop_time = 0)
+    buff = [SNAPSHOT_REQUEST].pack('C')
+
+    buff += [ticket].pack('N')
+    buff += strToSizedUTF16(name_pattern)
+    buff += [attribute_patterns.length].pack('N')
+
+    attribute_patterns.each{|pattern|
+      buff += strToSizedUTF16(pattern)
+    }
+
+    buff += packuint64(start_time)
+    buff += packuint64(stop_time)
+
+    #Send the message with its length prepended to the front
+    @socket.send("#{[buff.length].pack('N')}#{buff}", 0)
+  end
+
+  def sendRangeRequest(name_pattern, attribute_patterns, ticket, start_time, stop_time)
+    buff = [RANGE_REQUEST].pack('C')
+
+    buff += [ticket].pack('N')
+    buff += strToSizedUTF16(name_pattern)
+    buff += [attribute_patterns.length].pack('N')
+
+    attribute_patterns.each{|pattern|
+      buff += strToSizedUTF16(pattern)
+    }
+
+    buff += packuint64(start_time)
+    buff += packuint64(stop_time)
+
+    #Send the message with its length prepended to the front
+    @socket.send("#{[buff.length].pack('N')}#{buff}", 0)
+  end
+
+  def sendStreamRequest(name_pattern, attribute_patterns, update_interval, ticket)
+    buff = [STREAM_REQUEST].pack('C')
+
+    buff += [ticket].pack('N')
+    buff += strToSizedUTF16(name_pattern)
+    buff += [attribute_patterns.length].pack('N')
+
+    attribute_patterns.each{|pattern|
+      buff += strToSizedUTF16(pattern)
+    }
+
+    buff += packuint64(0)
+    buff += packuint64(update_interval)
+
+    #Send the message with its length prepended to the front
+    @socket.send("#{[buff.length].pack('N')}#{buff}", 0)
+  end
+
+  def sendURISearch(name_pattern)
+    buff = [URI_SEARCH].pack('C')
+    buff += strToUnicode(name_pattern)
+    #Send the message with its length prepended to the front
+    @socket.send("#{[buff.length].pack('N')}#{buff}", 0)
+  end
+
+end
+

data/lib/libowl/message_constants.rb

@@ -0,0 +1,27 @@
+#Message constants that indicate the purpose of a message
+
+#Keep alive message
+KEEP_ALIVE       = 0;
+#Request a snapshot of the current world model state
+SNAPSHOT_REQUEST = 1;
+#Request a snapshot of the wm state in a time range
+RANGE_REQUEST    = 2;
+#Request a stream of data from the world model
+STREAM_REQUEST   = 3;
+#Alias an attribute from the world model
+ATTRIBUTE_ALIAS  = 4;
+#Alias an origin from the world model
+ORIGIN_ALIAS     = 5;
+#Finish a request
+REQUEST_COMPLETE = 6;
+#Cancel a request
+CANCEL_REQUEST   = 7;
+#Message contains a data response from the world model
+DATA_RESPONSE    = 8;
+#Search names in the world model
+URI_SEARCH       = 9;
+#Response to a uri search message.
+URI_RESPONSE     = 10;
+#Set a preference for some data origins
+ORIGIN_PREFERENCE = 11;
+

data/lib/libowl/response.rb

@@ -0,0 +1,72 @@
+################################################################################
+#This file defines the Response class, an object that represents data from
+#an owl world model that is sent for a non-streaming request.
+#
+# Copyright (c) 2013 Bernhard Firner
+# All rights reserved.
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
+# or visit http://www.gnu.org/licenses/gpl-2.0.html
+#
+################################################################################
+
+#Response of a client request to the world model
+class Response
+  ##
+  #Initialize with the ClientWorldConnection that spawed this Response and
+  #the key of the request.
+  def initialize(cwc, key)
+    @cwc = cwc
+    @request_key = key
+  end
+
+  ##
+  #Get the data of this Response, blocking until that data is ready or
+  #an error occurs.
+  def get()
+    while (not (ready() or isError()))
+      sleep(1)
+    end
+    if (isError())
+      raise getError()
+    else
+      return @cwc.getNext(@request_key)
+    end
+  end
+
+  ##
+  #Returns true if data is available for a call to get().
+  def ready()
+    return @cwc.hasNext(@request_key)
+  end
+
+  ##
+  #Returns true if an error has occured.
+  def isError()
+    return @cwc.hasError(@request_key)
+  end
+
+  ##
+  #Get the error that occured.
+  def getError()
+    return @cwc.getError(@request_key)
+  end
+
+  ##
+  #Cancel this request.
+  def cancel()
+    return @cwc.cancelRequest(@request_key)
+  end
+end

data/lib/libowl/sensor_sample.rb

@@ -0,0 +1,17 @@
+#Sensor sample format
+class SensorSample
+  attr_accessor :phy_layer, :device_id, :receiver_id, :timestamp, :rssi, :sense_data
+
+  def initialize(phy, device_id, receiver_id, timestamp, rssi, sense_data)
+    @phy_layer = phy
+    @device_id = device_id
+    @receiver_id = receiver_id
+    @timestamp = timestamp
+    @rssi = rssi
+    @sense_data = sense_data
+  end
+
+  def to_s()
+    return "#{@timestamp}: (phy #{@phy_layer}) #{@device_id} -> #{@receiver_id}, RSS:#{@rssi}, Datalength:#{@sense_data.length} Data:#{@sense_data.unpack('C*').join(', ')}"
+  end
+end

data/lib/libowl/solution_types.rb

@@ -0,0 +1,49 @@
+#Solution types used when communicating with the distributor
+
+class SolutionType
+  #Used for auto-incremented alias numbers
+  @@num_aliases = 0
+  attr_accessor :type_alias, :data_uri
+  #Number to refer to this type
+  @type_alias
+  #The uri of this type
+  @data_uri
+  
+  def initialize(uri, type_alias = -1)
+    @data_uri = uri
+    #Auto-increment to the next alias number if one wasn't explicitly provided
+    if (type_alias >= 0)
+      @type_alias = type_alias
+    else
+      @type_alias = @@num_aliases
+      @@num_aliases += 1
+    end
+  end
+end
+
+class SolutionData
+  attr_accessor :region, :time, :target, :sol_name, :data
+  #Region of the solution
+  @region
+  #Time of the solution (milliseconds since midnight Jan 1, 1970)
+  @time
+  #Target of the solution
+  @target
+  #Name of this solution
+  @sol_name
+  #Binary buffer with solution data
+  @data
+
+  def initialize(region, time, target, sol_name, data)
+    @region = region
+    @time = time
+    @target = target
+    @sol_name = sol_name
+    @data = data
+  end
+
+  def to_s()
+    return "#{@region}:#{@target}:#{@sol_name} @ time #{@time} -> #{@data.unpack('H*')}"
+  end
+end
+

data/lib/libowl/solver_aggregator.rb

@@ -0,0 +1,126 @@
+#This class abstracts the details of connecting to a
+#GRAIL3 aggregator as a solver.
+#Solvers subscribe to the aggregator and then receive packets.
+
+require 'socket'
+require 'libowl/buffer_manip.rb'
+require 'libowl/aggregator_rules.rb'
+require 'libowl/sensor_sample.rb'
+
+class SolverAggregator
+  #Message constants
+  KEEP_ALIVE            = 0
+  CERTIFICATE           = 1
+  ACK_CERTIFICATE       = 2 #There is no message for certificate denial
+  SUBSCRIPTION_REQUEST  = 3
+  SUBSCRIPTION_RESPONSE = 4
+  DEVICE_POSITION       = 5
+  SERVER_SAMPLE         = 6
+  BUFFER_OVERRUN        = 7
+
+  attr_accessor :available_packets, :cur_rules, :connected
+  @available_packets
+  @cur_rules
+
+  def initialize(host, port)
+    @connected = false
+    @host = host
+    @port = port
+    @socket = TCPSocket.open(host, port)
+    handshake = ""
+    ver_string = "GRAIL solver protocol"
+    #The handshake is the length of the message, the protocol string, and the version (0).
+    handshake << [ver_string.length].pack('N') << ver_string << "\x00\x00"
+    #Receive a handshake and then send one
+    @socket.recvfrom(handshake.length)
+    @socket.send(handshake, 0)
+
+    @available_packets = []
+    @cur_rules = []
+  end
+
+  def close()
+    @socket.close()
+    @connected = false
+  end
+
+  #Handle a message of currently unknown type
+  def handleMessage()
+    #Get the message length as n unsigned integer
+    inlen = (@socket.recvfrom(4)[0]).unpack('N')[0]
+    if (nil == inlen) then
+      return nil
+    end
+    inbuff = @socket.recvfrom(inlen)[0]
+    #Byte that indicates message type
+    control = inbuff.unpack('C')[0]
+    case control
+    when SUBSCRIPTION_RESPONSE
+      decodeSubResponse(inbuff[1, inbuff.length - 1])
+      return SUBSCRIPTION_RESPONSE
+    when SERVER_SAMPLE
+      decodeServerSample(inbuff[1, inbuff.length - 1])
+      return SERVER_SAMPLE
+    else
+      KEEP_ALIVE
+    end
+  end
+
+  #Decode a subscription response and store the current rules in @cur_rules
+  def decodeSubResponse(inbuff)
+    puts "Got subscription response!"
+    num_rules = inbuff.unpack('N')[0]
+    rest = inbuff[4, inbuff.length - 1]
+    rules = []
+    for i in 1..num_rules do
+      phy_layer, num_txers = rest.unpack('CN')
+      txlist = []
+      rest = rest[5, rest.length - 1]
+      for j in 1..num_txers do
+        txlist.push([rest[0, 16], rest[16, 16]])
+        rest = rest[32, rest.length - 1]
+      end
+      update_interval = unpackuint64(rest)
+      rest = rest[8, rest.length - 1]
+      rule = AggrRule.new(phy_layer, txlist, update_interval)
+      rules.push(rule)
+    end
+    @cur_rules = rules
+  end
+
+  #Decode a server sample message
+  def decodeServerSample(inbuff)
+    if (inbuff != nil)
+      phy_layer = inbuff.unpack('C')
+      rest = inbuff[1, inbuff.length - 1]
+      txid = unpackuint128(rest)
+      rxid = unpackuint128(rest[16, rest.length - 1])
+      rest = rest[32, rest.length - 1]
+      timestamp, rssi = rest.unpack('Gg')
+      sense_data = rest[12, rest.length - 1]
+      @available_packets.push(SensorSample.new(phy_layer, txid, rxid, timestamp, rssi, sense_data))
+    end
+  end
+
+  def sendSubscription(rules)
+    #Start assembling a request message
+    buff = [SUBSCRIPTION_REQUEST].pack('C')
+    #Number of rules
+    buff += [rules.length].pack('N')
+    for rule in rules do
+      buff += [rule.phy_layer].pack('C')
+      buff += [rule.txers.length].pack('N')
+      #Push each transmitter/mask pair
+      for txer in rule.txers do
+        buff += txer.id + txer.mask
+      end
+      buff += packuint64(rule.update_interval)
+    end
+    #Send the message prepended with the length
+    @socket.send("#{[buff.length].pack('N')}#{buff}", 0)
+
+    #Get the subscription response
+    handleMessage()
+  end
+
+end