Class: Xap::Schema::XapBscDevice

Inherits:
XapDevice show all
Defined in:
lib/xap/schema/xap_bsc_device.rb

Overview

Represents an xAP BSC Device. See the xAP Basic Status and Control Schema. www.xapautomation.org/index.php?title=Basic_Status_and_Control_Schema

Instance Attribute Summary

Attributes inherited from XapDevice

#address, #interval, #uid

Instance Method Summary collapse

Methods inherited from XapDevice

#to_s

Constructor Details

#initialize(address, uid, endpoints, interval = 5) ⇒ XapBscDevice

Initializes an XapBscDevice with the given address, uid. Endpoints is an array of hashes containing :State, :Level, :Text, and/or optionally :DisplayText. :State should be a boolean value or nil, :Level should be an array of [numerator, denominator], and :Text and :DisplayText should be Strings. Each input and output block must also have an :endpoint key that contains the endpoint name for the given block and may include a :uid key that contains an integer from 1 to 254. Endpoint names and UIDs must be unique within this device. Output hashes (i.e. those endpoints that can be changed via xAP) are identified by including a :callback key that is a proc to be called with the endpoint hash when any of the output endpoint’s attributes are changed by an incoming xAP message.

See add_endpoint for a summary of endpoint fields.

Example:

XapBscDevice.new XapAddress.new(‘vendor’, ‘dev’, ‘hostname’), Xap.random_uid, [ { :endpoint => ‘Input 1’, :uid => 1, :State => true }, { :endpoint => ‘Output 1’, :State => true, :callback => proc { |ep| puts ‘Output 1’ } } ]



31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 31

def initialize address, uid, endpoints, interval = 5
  super address, uid, interval

  # TODO: Make endpoints a hash, with what is currently the
  # :endpoint field as the hash key, then store the hash key back
  # into the hash (will simplify calls to XapBscDevice.new, so
  # the user can type => instead of :endpoint)

  @input_count = 0
  @output_count = 0
  @endpoints = {} # Mapping from endpoint name to endpoint hash
  @uids = []
  @outputs = [] # Array containing only output endpoints to simplify handling command messages
  endpoints.each do |ep|
    add_endpoint ep
  end
end

Instance Method Details

#add_endpoint(ep) ⇒ Object

Adds a new endpoint hash to the list of endpoints, generating an xAPBSC.info message if the addition is successful. The endpoint’s name must be unique. UID collision will result in an exception being raised. If the UID is not specified, the lowest available UID will be used.

Summary of endpoint fields: :endpoint - Name of endpoint - mandatory, must be unique when downcased, String :uid - UID of endpoint - optional, must be unique, Fixnum 1-254 :callback - Output change callback - mandatory for outputs, may be nil :State - On/off/? state - mandatory according to xAP BSC spec :Level - numerator / denominator - optional :Text - Stream text - optional (mutually exclusive with :Level according to xAP BSC spec) :DisplayText - UI display text - optional

Example: add_endpoint { :endpoint => ‘Input 1’, :uid => 4, :State => false, :Level => [ 0, 30 ] }



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 153

def add_endpoint ep
  unless ep.include?(:endpoint) && ep.include?(:State) && (!ep.include?(:uid) || ep[:uid].is_a?(Fixnum))
    raise 'An endpoint is missing one or more required fields (:endpoint, :State).'
  end

  raise "Duplicate endpoint name #{ep[:endpoint]}." if @endpoints.include? ep[:endpoint].downcase

  ep[:uid] ||= find_free_uid
  raise "Duplicate UID #{ep[:uid]}." if @uids[ep[:uid]]

  # TODO: Additional verification of :Level, :Text, and :DisplayText

  if ep.include? :callback
    @output_count = @output_count + 1
    @outputs << ep
  else
    @input_count = @input_count + 1
  end

  @endpoints[ep[:endpoint].downcase] = ep
  @uids[ep[:uid]] = ep

  send_info ep if @handler
end

#find_free_uid ⇒ Object

Finds and returns the lowest-available endpoint UID, or nil if there are no free endpoint IDs.



195
196
197
198
199
200
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 195

def find_free_uid
  for idx in 1..254
    return idx unless @uids[idx]
  end
  nil
end

#get_display_text(endpoint) ⇒ Object

Returns the DisplayText field of the endpoint with the given name.



282
283
284
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 282

def get_display_text endpoint
  @endpoints[endpoint.downcase][:DisplayText]
end

#get_level(endpoint) ⇒ Object

Returns the Level field of the endpoint with the given name.



231
232
233
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 231

def get_level endpoint
  @endpoints[endpoint.downcase][:Level]
end

#get_state(endpoint) ⇒ Object

Returns the State field of the endpoint with the given name.



209
210
211
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 209

def get_state endpoint
  @endpoints[endpoint.downcase][:State]
end

#get_text(endpoint) ⇒ Object

Returns the Text field of the endpoint with the given name.



261
262
263
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 261

def get_text endpoint
  @endpoints[endpoint.downcase][:Text]
end

#get_uid(endpoint) ⇒ Object

Returns the UID for the endpoint with the given name, or nil if no such endpoint exists.



204
205
206
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 204

def get_uid endpoint
  @endpoints[endpoint.downcase][:uid]
end

#handler=(handler) ⇒ Object

Assigns the handler that owns this device, then sends the initial state of all input and output blocks as xAPBSC.info messages.



51
52
53
54
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 51

def handler= handler
  super handler
  announce_endpoints
end

#receive_message(msg) ⇒ Object

Called when a message targeting this device’s address is received.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 71

def receive_message msg
  if msg.is_a? XapBscCommand
    Xap.log "Command message for #{self}"

    if @output_count > 0
      eps = []
      if msg.target_addr.wildcard?
        @outputs.each do |out|
          eps << out if msg.target_addr.endpoint_match out[:endpoint]
        end
      else
        ep = @endpoints[msg.target_addr.endpoint.downcase]
        eps << ep if ep
      end

      # For each message block, if ID=*, apply the
      # change to all matched endpoints.  If ID!=*,
      # apply the change to the matching endpoint,
      # iff that endpoint is in the eps list.
      msg.each_block do |blk|
        id = blk.id
        if id == nil || id == '*'
          eps.each do |ep|
            update_endpoint ep, blk
          end
        else
          ep = @uids[id.to_i]
          if ep && eps.include?(ep)
            update_endpoint ep, blk
          end
        end
      end
    end

  elsif msg.is_a? XapBscQuery
    Xap.log "Query message for #{self}, target #{msg.target_addr}, wildcard #{msg.target_addr.wildcard?}"

    if msg.target_addr.wildcard?
      @endpoints.each do |name, ep|
        if msg.target_addr.endpoint_match name
          Xap.log "Matching endpoint found: #{ep[:endpoint]}"
          send_info ep
        end
      end
    elsif msg.target_addr.endpoint
      ep = @endpoints[msg.target_addr.endpoint.to_s.downcase]
      if ep
        Xap.log "Matching endpoint found: #{ep[:endpoint]}"
        send_info ep
      else
        Xap.log "No matching endpoint found"
      end
    else
      Xap.log "Error: No endpoint was given in the query"
    end

  elsif msg.is_a? XapBscInfo
    Xap.log "Info message for #{self}"

  elsif msg.is_a? XapBscEvent
    Xap.log "Event message for #{self}"

  end
end

#remove_endpoint(ep) ⇒ Object

Removes the given endpoint, which may be the endpoint hash or name. Doesn’t verify that the endpoint actually exists.



180
181
182
183
184
185
186
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 180

def remove_endpoint ep
  if ep.is_a? String
    ep = @endpoints[ep.downcase]
  end
  @endpoints.delete ep[:endpoint].downcase
  @uids[ep[:uid]] = nil
end

#set_address(address) ⇒ Object

Sets the xAP address of this virtual device, then sends an xAPBSC.info message for all endpoints.



65
66
67
68
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 65

def set_address address
  super address
  announce_endpoints
end

#set_display_text(endpoint, text) ⇒ Object

Sets the DisplayText field of the endpoint with the given name. If the new state is different from the old state, an event message will be generated. Otherwise, an info message will be generated.



289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 289

def set_display_text endpoint, text
  ep = @endpoints[endpoint.downcase]

  old = ep[:DisplayText]
  ep[:DisplayText] = old

  if text != old
    send_event ep
  else
    send_info ep
  end
end

#set_level(endpoint, level) ⇒ Object

Sets the Level field of the endpoint with the given name. If level is an array, then both the numerator and denominator are replaced. If level is a Fixnum, only the numerator is replaced. If the new level is different from the old level, an event message will be generated. Otherwise, an info message will be generated. Error checking is not performed on the level parameter. Pass nil to remove the level from this endpoint.



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 242

def set_level endpoint, level
  ep = @endpoints[endpoint.downcase]

  old = ep[:Level]
  if level != nil
    level = [ level, ep[:Level][1] ] if level.is_a? Fixnum
    ep[:Level] = level
  else
    ep.delete :Level
  end

  if level != old
    send_event ep
  else
    send_info ep
  end
end

#set_state(endpoint, state) ⇒ Object

Sets the State field of the endpoint with the given name. If the new state is different from the old state, an event message will be generated. Otherwise, an info message will be generated.



216
217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 216

def set_state endpoint, state
  raise 'state must be true, false, or nil.' unless state == true || state == false || state == nil

  ep = @endpoints[endpoint.downcase]
  old = ep[:State]
  ep[:State] = state

  if state != old
    send_event ep
  else
    send_info ep
  end
end

#set_text(endpoint, text) ⇒ Object

Sets the Text field of the endpoint with the given name. If the new state is different from the old state, an event message will be generated. Otherwise, an info message will be generated.



268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 268

def set_text endpoint, text
  ep = @endpoints[endpoint.downcase]

  old = ep[:Text]
  ep[:Text] = old

  if text != old
    send_event ep
  else
    send_info ep
  end
end

#uid=(uid) ⇒ Object

Sets the xAP UID of this virtual device, then sends an xAPBSC.info message for all endpoints.



58
59
60
61
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 58

def uid= uid
  super uid
  announce_endpoints
end

#uid_endpoint(uid) ⇒ Object

Returns the endpoint having the given UID, if any.



189
190
191
 
# File 'lib/xap/schema/xap_bsc_device.rb', line 189

def uid_endpoint uid
  @uids[uid]
end