ansible4ozw 0.0.1

data/lib/ansible/knx/knx_scene.rb

@@ -0,0 +1,48 @@
+=begin
+Project Ansible  - An extensible home automation scripting framework
+----------------------------------------------------
+Copyright (c) 2011 Elias Karakoulakis <elias.karakoulakis@gmail.com>
+
+SOFTWARE NOTICE AND LICENSE
+
+Project Ansible is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+Project Ansible 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 Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Project Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+for more information on the LGPL, see:
+http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License
+=end
+
+module Ansible
+    
+    module KNX
+        
+        # KNX Scene control module
+        module Scene
+            
+            @scene_values = {}
+            
+            def store(scene_id)
+                @scene_values[scene_id] = @current_value
+            end
+            
+            def recall(scene_id)
+                if val = @scene_values[scene_id] then
+                    set(scene_id)
+                end
+            end
+            
+        end
+        
+    end
+    
+end

data/lib/ansible/knx/knx_tools.rb

@@ -0,0 +1,76 @@
+=begin
+Project Ansible  - An extensible home automation scripting framework
+----------------------------------------------------
+Copyright (c) 2011 Elias Karakoulakis <elias.karakoulakis@gmail.com>
+
+SOFTWARE NOTICE AND LICENSE
+
+Project Ansible is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+Project Ansible 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 Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Project Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+for more information on the LGPL, see:
+http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License
+=end
+    
+# various KNX tool functions
+
+# addr2str: Convert an integer to an EIB address string, in the form "1/2/3" or "1.2.3"
+def addr2str(a, ga=false)
+    str=""
+    if a.is_a?Array then
+        #~ a = a[0]*256+a[1]
+        a = a.pack('c*').unpack('n')[0]
+    end
+    if (ga)
+        str = "#{(a >> 11) & 0xf}/#{(a >> 8) & 0x7}/#{a & 0xff}"
+    else
+        str = "#{a >> 12}.#{(a >> 8) & 0xf}.#{a & 0xff}"
+    end
+    return(str)
+end
+
+# str2addr: Parse an address string into an unsigned 16-bit integer
+def str2addr(s)
+    if m = s.match(/(\d*)\/(\d*)\/(\d*)/)
+        a, b, c = m[1].to_i, m[2].to_i, m[3].to_i
+        return ((a & 0x01f) << 11) | ((b & 0x07) << 8) | ((c & 0xff))
+    end
+    if m = s.match(/(\d*)\/(\d*)/)
+        a,b = m[1].to_i, m[2].to_i
+        return ((a & 0x01f) << 11) | ((b & 0x7FF))
+    end
+    if s.start_with?("0x")
+        return (s.to_i & 0xffff)
+    end
+end
+
+def decode_framedata(data)
+    case data
+    when Fixnum then "0x"+data.to_s(16).upcase
+    when Array then data.collect{|b| "0x"+b.to_s(16).upcase}
+    when String then data.unpack('C*').collect{|b| "0x"+b.to_s(16).upcase}
+    else data
+    end
+end
+
+def frame_inspect(frame)
+    return "#{Time.now.strftime('%a %d/%m/%Y %H:%M:%S %Z')}: #{Ansible::KNX::APCICODES[frame.apci]}" +  
+    " prio=#{Ansible::KNX::PRIOCLASSES[frame.prio_class]}" + " len=#{frame.datalength}" +
+    " from #{addr2str(frame.src_addr)} to #{addr2str(frame.dst_addr, frame.daf)}" +
+    " data=" + decode_framedata(frame.datalength > 1 ? frame.data : frame.apci_data).inspect   
+end
+
+#ga = 17*256 + 200
+#~ ga = [17, 200]
+#~ puts(addr2str(ga))
+#~ dest= str2addr("1/2/0")

data/lib/ansible/knx/knx_transceiver.rb

@@ -0,0 +1,237 @@
+=begin
+Project Ansible  - An extensible home automation scripting framework
+----------------------------------------------------
+Copyright (c) 2011 Elias Karakoulakis <elias.karakoulakis@gmail.com>
+
+SOFTWARE NOTICE AND LICENSE
+
+Project Ansible is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+Project Ansible 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 Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Project Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+for more information on the LGPL, see:
+http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License
+=end
+
+require 'cgi'
+
+require 'config'
+require 'transceiver'
+require 'EIBConnection'
+require 'ansible_callback'
+require 'knx_protocol'
+require 'knx_value'
+require 'knx_tools'
+
+module Ansible
+
+    module KNX
+        
+        #
+        # The KNX Transceiver is an object responsible for i/o with the KNX bus. 
+        # It does so using eibd, part of BCU-SDK the open-source libary for KNX. 
+        class KNX_Transceiver < Transceiver
+            include AnsibleCallback
+            
+            # a special exception to break the knx tranceiver loop
+            class NormalExit < Exception; end
+                
+            attr_reader :stomp
+            
+            # initialize a KNXTranceiver
+            #
+            # *params:
+            #   [connURL] an eibd connection URL. see eibd --help for acceptable values
+            def initialize(connURL=KNX_URL)
+                raise "Already initialized!" unless  Ansible::KNX::KNXValue.transceiver.nil?
+                @connURL = connURL
+                @monitor_conn_ok, @send_conn_ok = false, false
+                @send_mutex = Mutex.new()
+                @knxbuf = EIBBuffer.new()
+                #
+                super()
+                # store reference to ourselves to the classes that use us
+                Ansible::KNX::KNXValue.transceiver = self
+                # register default handler for KNX frames
+                add_callback(:onKNXtelegram) { | sender, cb, frame |
+                    puts(frame_inspect(frame)) if $DEBUG
+                    case frame.apci.value
+                    when 0 then # A_GroupValue_Read
+                        puts "read request for knx address #{addr2str(frame.dst_addr, frame.daf)}"
+                        AnsibleValue[:groups => [frame.dst_addr]].each { |v|
+                            unless v.current_value.nil? then
+                                puts "==> responding with value #{v}"
+                                send_apdu_raw(frame.dst_addr, v.to_apdu(0x40))
+                            end
+                        }
+                    when 1 then # A_GroupValue_Response
+                        puts "response frame by #{addr2str(frame.src_addr)} for knx address #{addr2str(frame.dst_addr, frame.daf)}"
+                        AnsibleValue[:groups => [frame.dst_addr]].each { |v|
+                            v.update_from_frame(frame)
+                            puts "synchronized knx value #{v} from frame #{frame.inspect}" if $DEBUG
+                        }
+                    when 2 then # A_GroupValue_Write
+                        AnsibleValue[:groups => [frame.dst_addr]].each { |v|
+                            v.update_from_frame(frame)
+                            puts "updated knx value #{v} from frame #{frame.inspect}" if $DEBUG
+                        }
+                    end
+                }
+            end
+            
+            # initialize eibd connection
+            def init_eibd(conn_symbol, conn_ok_symbol)
+                unless instance_variable_get(conn_ok_symbol)
+                    begin
+                        puts("KNX: init #{conn_symbol} to #{@connURL}")
+                        conn = EIBConnection.new()
+                        conn.EIBSocketURL(@connURL)
+                        instance_variable_set(conn_symbol, conn)
+                        instance_variable_set(conn_ok_symbol, true)
+                        return(conn)
+                    rescue Errno::ECONNRESET => e
+                        conn.EIBClose
+                        instance_variable_set(conn_ok_symbol, false)
+                        puts "init_eibd: Disconnected, retrying in 10 seconds..."
+                        sleep(10)
+                    end
+                end
+            end
+            
+            # get handle to eibd monitor connection
+            def eibd_connection(conn_symbol, conn_ok_symbol)
+                if instance_variable_get(conn_ok_symbol) then
+                    return(instance_variable_get(conn_symbol))
+                else
+                    init_eibd(conn_symbol, conn_ok_symbol)
+                end
+            end
+
+            # get handle to KNX monitoring connection, reconnecting if necessary
+            def monitor_conn; return(eibd_connection(:@monitor_conn, :@monitor_conn_ok)); end
+               
+            # get handle to KNX sending connection, reconnecting if necessary
+            def send_conn; return(eibd_connection(:@send_conn, :@send_conn_ok)); end
+                
+            # the main KNX transceiver thread
+            def run()
+                puts("KNX Transceiver thread is running!")
+                @stomp = nil
+                begin
+                    #### part 1: connect to STOMP broker
+                    @stomp = OnStomp.connect(STOMP_URL)
+                    #### part 2: subscribe to command channel, listen for messages and pass them to KNX
+                    # @stomp.subscribe KNX_COMMAND_TOPIC do |msg|
+                        # dest = msg.headers['dest_addr'].to_i
+                        # #TODO: check address limits
+                        # apdu = Marshal.load(CGI.unescape(msg.body))
+                        # send_apdu_raw(dest, apdu)
+                    # end
+                    ##### part 3: monitor KNX bus, post all activity to /knx/monitor
+                    vbm = monitor_conn.EIBOpenVBusmonitor()
+                    loop do
+                        len = monitor_conn.EIBGetBusmonitorPacket(@knxbuf)
+                        #puts "knxbuffer=="+@knxbuf.buffer.inspect
+                        frame = L_DATA_Frame.read(@knxbuf.buffer.pack('c*'))
+                        #puts "frame:\n\t"
+                        headers = {}
+                        frame.field_names.each { |fieldname|
+                            field = frame.send(fieldname)
+                            #puts "\t#{fieldname} == #{field.value}"
+                            headers[fieldname] = CGI.escape(field.value.to_s)
+                        }
+                        @stomp.send(KNX_MONITOR_TOPIC, "KNX Activity", headers)
+                        #puts Ansible::KNX::APCICODES[frame.apci] + " packet from " + 
+                        #  addr2str(frame.src_addr) + " to " + addr2str(frame.dst_addr, frame.daf) + 
+                        #  "  priority=" + Ansible::KNX::PRIOCLASSES[frame.prio_class]
+                        fire_callback(:onKNXtelegram, frame.dst_addr, frame)
+                        # 
+                    end
+                rescue Errno::ECONNRESET => e
+                    @monitor_conn_ok = false
+                    puts("EIBD disconnected! retrying in 10 seconds..")
+                    sleep(10)
+                    retry                    
+                rescue NormalExit => e
+                    puts("KNX transceiver terminating gracefully...")
+                rescue Exception => e
+                    puts("Exception in KNX server thread: #{e}")
+                    puts("backtrace:\n  " << e.backtrace.join("\n  "))
+                    sleep(3)
+                    retry
+#                ensure
+                    #puts "Closing EIB connection..."
+                    #@monitor_conn.EIBClose() if @monitor_conn
+                    #puts "Closing STOMP connection..."
+                    #@stomp.disconnect if @stomp
+                end
+            end #def run()
+        
+            # send a raw APDU to the KNX bus.
+            #
+            # * Arguments: 
+            #   [dest]  destination (16-bit integer)
+            #   [apdu] raw APDU (binary string)       
+            def send_apdu_raw(dest, apdu)
+                @send_mutex.synchronize {
+                    raise 'apdu must be a byte array!' unless apdu.is_a?Array
+                    puts("KNX transceiver: sending to group address #{dest}, #{apdu.inspect}") if $DEBUG
+                    if (send_conn.EIBOpenT_Group(dest, 1) == -1) then
+                        raise("KNX client: error setting socket mode")
+                    end
+                    send_conn.EIBSendAPDU(apdu)
+                    send_conn.EIBReset()
+                }
+            end
+            
+            # (Try to) read a groupaddr from eibd cache.
+            #
+            # return it if found, otherwise query the bus. In the latter case, 
+            # the main receiver thread (in run()) will act on the response.
+            #
+            # * Arguments: 
+            #   [ga]    Fixnum: group address (0-65535)
+            #   [cache_only] boolean: when true, do not query the bus   
+            def read_eibd_cache(ga, cache_only=false)
+                src = EIBAddr.new()
+                buf = EIBBuffer.new()
+                result = nil
+                @send_mutex.synchronize {
+                    # query eibd for a cached value
+                    if (send_conn.EIB_Cache_Read_Sync(ga, src, buf, 0) == -1) then
+                        # value not found in cache
+                        puts "groupaddress #{addr2str(ga, true)} not found in cache."
+                        unless cache_only then
+                            puts ".. requesting value on bus .."
+                            if (send_conn.EIBOpenT_Group(ga, 1) == -1) then
+                                raise("KNX client: error setting socket mode")
+                            end
+                            # send a read request to the bus
+                            send_conn.EIBSendAPDU([0,0x00])
+                        end
+                        send_conn.EIBReset()
+                    else
+                        send_conn.EIBReset()
+                        # value found in cache..
+                        puts "found in cache, last sender was #{addr2str(src.data)}"
+                        result = buf.buffer
+                    end
+                }
+                return result
+            end
+            
+        end #class 
+
+    end #module KNX
+    
+end #module Ansible
+

data/lib/ansible/knx/knx_value.rb

@@ -0,0 +1,327 @@
+=begin
+Project Ansible  - An extensible home automation scripting framework
+----------------------------------------------------
+Copyright (c) 2011 Elias Karakoulakis <elias.karakoulakis@gmail.com>
+
+SOFTWARE NOTICE AND LICENSE
+
+Project Ansible is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published
+by the Free Software Foundation, either version 3 of the License,
+or (at your option) any later version.
+
+Project Ansible 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 Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with Project Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+for more information on the LGPL, see:
+http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License
+=end
+
+require 'ansible_value'
+
+require 'knx_transceiver'
+require 'knx_protocol'
+require 'knx_tools'
+require 'knx_dpt'
+
+module Ansible
+    
+    module KNX
+        
+        # a KNXValue is a device-dependant datapoint. It is initialized by a  
+        # DPT type name (e.g. "1.001" for binary switch) and is extended 
+        # by the initializer with the corresponding DPT module (e.g. KNX::DPT1)
+        # so as to handle DPT1 frames.
+        # Each KNXValue is linked to zero or more group addresses, the first
+        # of which will be the "update" value
+        class KNXValue
+            
+            include AnsibleValue
+            
+            #
+            # ------ CLASS VARIABLES & METHODS
+            #
+            @@ids = 0
+            def KNXValue.id_generator
+                @@ids = @@ids + 1
+                return @@ids
+            end
+    
+            # a Hash containing all known group addresses
+            @@AllGroups = {}
+            
+            # the transceiver responsible for all things KNX
+            @@transceiver = nil
+            def KNXValue.transceiver; return @@transceiver; end
+            def KNXValue.transceiver=(other); 
+                @@transceiver = other if other.is_a? Ansible::KNX::KNX_Transceiver
+            end
+            
+            #
+            # ----- INSTANCE VARIABLES & METHODS
+            #
+                    
+            # equality checking
+            def == (other)
+                return (other.is_a?(KNXValue) and (@id == other.id))
+            end
+
+            # set flag: knxvalue.flags[:r] = true
+            # get flag: knxvalue.flags[:r]  (evaluates to true, meaning the read flag is set)
+            attr_reader :flags
+            attr_reader :groups 
+            attr_reader :dpt_basetype, :dpt_subtype, :id
+            attr_accessor :description
+    
+            # initialize a KNXValue
+            # ===Arguments: 
+            # [dpt] 
+            #   string representing the DPT (datapoint type) of the value
+            #   e.g. "5.001" meaning DPT5 percentage value (8-bit unsigned)
+            # [groups] 
+            #   array of group addresses associated with this datapoint
+            # [flags]  
+            #   hash of symbol=>boolean flags regarding its behaviour
+            #   e.g. {:r => true} the value can only respond to read requests on the KNX bus.
+            #   default flags: READ and WRITE
+            #       c => Communication
+            #       r => Read
+            #       w => Write
+            #       t => Transmit
+            #       u => Update
+            #       i => read on Init
+            def initialize(dpt, groups=[], flags=nil)
+                
+                # init DPT info
+                if md = /(\d*)\.(\d*)/.match(dpt) then
+                    @dpt = dpt
+                    @dpt_mod = Ansible::KNX.module_eval("DPT#{md[1]}")
+                    raise "unknown/undeclared DPT module #{dpt}" unless @dpt_mod.is_a?Module
+                    @parserclass = @dpt_mod.module_eval("DPT#{md[1]}_Frame")
+                    raise "unknown/undeclared parser for DPT #{dpt}" unless @parserclass.ancestors.include?(DPTFrame)
+                    @dpt_basetype = @dpt_mod::Basetype
+                    raise "missing Basetype info for #{dpt}" unless @dpt_basetype.is_a?Hash
+                    @dpt_subtype = @dpt_mod::Subtypes[md[2]]
+                    raise "missing sybtype info for #{dpt}" unless @dpt_subtype.is_a?Hash
+                    # extend this object with DPT-specific module 
+                    self.extend(@dpt_mod)
+                    # print out some useful debug info                    
+                    puts "  dpt_basetype = #{@dpt_basetype},  dpt_subtype = #{@dpt_subtype}" if $DEBUG
+                else
+                    raise "invalid datapoint type (#{dpt})"
+                end
+                
+                # array of GroupAddress objects associated with this datapoint
+                # only the first address is used in a  write operation (TODO: CHECKME)
+                @groups = case groups
+                    when Fixnum then Array[group]
+                    when String then Array[str2addr(groups)] 
+                    when Array then groups
+                end
+                
+                # store DPT info about these group addresses
+                @groups.each { |grp|
+                    # sanity check: is this groupaddr already decaled as a different basetype?
+                    # FIXME: specs dont forbid it, only check required is datalength compatibility
+                    if @@AllGroups[grp] and (old_dpt = @@AllGroups[grp][:dpt_basetype]) and not (old_dpt.eql?(@dpt_basetype))                           
+                        raise "Group address #{addr2str(grp)} is already declared as DPT basetype #{old_dpt}!"
+                    end
+                    puts "adding groupaddr #{addr2str(grp,true) } (#{@dpt}: #{@dpt_subtype[:name]}), to global hash"
+                    @@AllGroups[grp] = {:basetype => @dpt_basetype, :subtype => @dpt_subtype}
+                }
+                
+                if flags.nil?
+                    # default flags: READ and WRITE
+                    @flags = {:r => true,:w => true}
+                else
+                    raise "flags parameter must be a Hash!" unless flags.is_a?Hash
+                    @flags = flags
+                end
+
+                # TODO: physical address: set only for remote nodes we are monitoring
+                # when left to nil, it/ means a datapoint on this KNXTransceiver 
+                @physaddr = nil
+                
+                # id of datapoint
+                # initialized by class method KNXValue.id_generator
+                @id = KNXValue.id_generator()
+                
+                @description = ''
+                
+                # store this KNXValue in the Ansible database
+                AnsibleValue.insert(self)
+            end
+
+            # is this KNX datapoint read only?
+            def read_only?
+                return((defined? @flags) and (@flags[:r] and not @flags[:w]))
+            end
+
+            # is this KNX datapoint write only?
+            def write_only?
+                return((defined? @flags) and (@flags[:w] and not @flags[:r]))
+            end
+            
+            # read value from eibd's group cache, or issue a read request,
+            # hoping that someone will respond with the last known status
+            # for this value
+            def read_value()
+                if (not @groups.nil?) and (group = @groups[0]) then
+                    if (data = @@transceiver.read_eibd_cache(group)) then
+                        fire_callback(:onReadCacheHit)
+                        # update the value
+                        update(@parserclass.read(data.pack('c*')))
+                    else
+                        # value not found in cache, maybe some other
+                        # device on the bus will respond...
+                        fire_callback(:onReadCacheMiss)
+                        nil
+                    end
+                else
+                    return false
+                end
+            end
+            
+            #
+            # write value to the bus
+            # argument: new_val according to DPT 
+            #   if :basic, then new_val is plain data value   
+            #   else (:composite) new_val is a hash of 
+            #       field_name => field_value pairs
+            #   all values get mapped using to_protocol_value() in AnsibleValue::update()
+            # return true if successful, false otherwise
+            def write_value(new_val)
+                #write value to primary group address
+                dest, telegram = nil, nil
+                if @groups.length > 0 then 
+                    dest = @groups[0]
+                else
+                    raise "#{self}: primary group address not set!!!"
+                end 
+                case @dpt_mod::Basetype[:valuetype]
+                when :basic then
+                    # basic value: single 'data' field
+                    telegram = @parserclass.new(:data => new_val)
+                when :composite then
+                    if new_val.is_a?Hash then
+                        telegram = @parserclass.new(new_val)
+                    else
+                        if @parserclass.methods.include?(:assign) then
+                            puts "FIXME"
+                        else
+                            raise "#{self} has a composite DPT, set() expects a hash!"
+                        end
+                    end
+                end
+                #
+                puts "#{self}: Writing new value (#{new_val}) to #{addr2str(dest, true)}"
+                #
+                if (@@transceiver.send_apdu_raw(dest, to_apdu(telegram, 0x80)) > -1) then
+                    update(telegram)
+                    return(true)
+                else
+                    return(false)
+                end
+            end
+            
+            # set primary group address
+            def group_primary=(grpaddr)
+                @groups.unshift(grpaddr)
+            end
+            
+            # assign a new array of group addresses for this datapoint
+            def groups=(other)
+                raise "KNXValue.groups= requires an array of at least one group addresses" unless (other.is_a?Array) and (other.length > 0)
+                @groups.replace(other)
+            end
+            
+            # make sure all frame fields are valid (within min,max range)
+            # see Ansible::AnsibleValue.update
+            def validate_ranges
+                if defined? @current_value then  
+                    @current_value.validate_ranges
+                end
+            end
+            
+            # create apdu for this KNXValue
+            # APDU types are:
+            #   0x00 => Read
+            #   0x40 => Response (default)
+            #   0x80 => Write
+            def to_apdu(frame, apci_code = 0x40)
+                apdu = if @dpt_mod::Basetype[:bitlength] <= 6 then
+                    #[0, apci_code | @current_value]
+                    [0, apci_code | frame.data]
+                else
+                    #[0, apci_code] + @current_value.to_a
+                    [0, apci_code] + frame.to_binary_s.unpack('C*') 
+                end
+                return apdu
+            end
+            
+            # update internal state from raw KNX frame
+            def update_from_frame(rawframe)
+                data = if @dpt_mod::Basetype[:bitlength] <= 6 then
+                    # bindata always expects a binary string
+                    [rawframe.apci_data].pack('c')
+                else
+                    rawframe.data
+                end
+                foo = @parserclass.read(data)
+                puts "update_from_frame: #{foo.class} = #{foo.inspect}"
+                update(foo)
+            end
+                
+            # human-readable representation of the value. Uses all field
+            # info from its DPT included module, if available.
+            def to_s
+                dpt_name = (@dpt_subtype.nil?) ? '' : @dpt_subtype[:name] 
+                dpt_info = "KNXValue[#{@dpt} #{dpt_name}]"
+                # add field values explanation, if any
+                vstr = (defined?(@current_value) ? explain(@current_value) : '(value undefined)')
+                # return @dpt: values.explained
+                gaddrs = @groups.collect{|ga| addr2str(ga, true)}.join(', ')
+                return [@description, gaddrs, dpt_info].compact.join(' ') + " : #{vstr}" 
+            end
+                        
+            # return a human-readable representation of a DPT frame
+            def explain(frame)
+                raise "explain() expects a DPTFrame, got a #{frame.class}" unless frame.is_a?DPTFrame
+                fielddata = []
+                # iterate over all available DPT fields
+                frame.field_names.each { |fieldname|
+                    # skip padding fields
+                    next if /pad/.match(fieldname)
+                    field = frame.send(fieldname)
+                    fval = field.value
+                    # get value encoding hashmap, if any
+                    vhash = getparam(:enc, field)
+                    # get value units
+                    units = getparam(:unit, field) 
+                    fval = as_canonical_value()
+                    # add field value, according to encoding hashtable
+                    fielddata << "#{(vhash.is_a?Hash) ? vhash[fval] : fval} #{units}"
+                } 
+                return fielddata.join(', ')
+            end            
+
+            # get a DPT parameter, trying to locate it in the following order:
+            #   1) in the DPTFrame field definition 
+            #   2) in the DPT subtype definition
+            #   3) in the DPT basetype definition
+            def getparam(param, field=nil)
+                return ((field and field.get_parameter(param)) or 
+                        (@dpt_subtype and @dpt_subtype[param]) or 
+                        (@dpt_basetype and @dpt_basetype[param]))
+            end
+            
+        end #class KNXValue
+    
+    end #module KNX
+    
+end #module Ansible