knx 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da3886255a22b8e72fe4843c9d572b8f55d0f24f
+  data.tar.gz: f13f7c99aa45592be334abe8d5fda818ed4a03a5
+SHA512:
+  metadata.gz: 1edd50db73644cc37edb56cdf2ac87375f39af1945df6ad957eb5dea19976a5c4d1545297fc754b51d66bc5e5a8c19544a4fe35645d1565e9b203a95e30df39f
+  data.tar.gz: 9146bc461808c8f06c56a5b3e256052ff95cb0ef0bb62d7eeac31e1b76e188f6f1ea560962a5a9a4efacab2b9ac4543ddcdc8bf6438c833894941cb0cc5e2ad7

data/README.md

@@ -0,0 +1,85 @@
+# Ruby KNX
+
+Constructs [KNX standard](https://en.wikipedia.org/wiki/KNX_(standard)) datagrams that make it easy to communicate with devices on KNX networks.
+It does not implement the transport layer so you can use it with naitive ruby, eventmachine, celluloid or the like.
+
+[![Build Status](https://travis-ci.org/acaprojects/ruby-knx.svg?branch=master)](https://travis-ci.org/acaprojects/ruby-knx)
+
+You'll need a gateway. I recommend one that supports TCP/IP such as [MDT Interfaces](http://www.mdt.de/EN_Interfaces.html) however you can use multicast groups if your network is configured to allow this.
+
+
+## Install the gem
+
+Install it with [RubyGems](https://rubygems.org/)
+
+    gem install knx
+
+or add this to your Gemfile if you use [Bundler](http://gembundler.com/):
+
+    gem 'knx'
+
+
+
+## Usage
+
+```ruby
+require 'knx'
+
+knx = KNX.new
+datagram = knx.read(byte_string)
+
+datagram.source_address.to_s
+# => '2.3.4'
+
+datagram.destination_address.to_s
+# => '3/4/5'
+
+datagram.data # Returns a byte array
+# => [1]
+
+# ...
+
+request = knx.action('1/2/0', true)
+byte_string = request.to_binary_s
+
+request = knx.action('1/2/3', 150)
+byte_string = request.to_binary_s
+
+# Send byte_string to KNX network to execute the request
+# Supports multicast, unicast and TCP/IP tunneling (when supported)
+
+```
+
+We also support [KNX BAOS devices](http://www.weinzierl.de/index.php/en/all-knx/knx-devices-en) devices:
+
+
+```ruby
+require 'knx/object_server'
+
+os = KNX::ObjectServer.new
+datagram = os.read(byte_string)
+
+# Can return multiple values
+datagram.data.length #=> 1
+
+# Get the item index we are reading
+datagram.data[0].id
+# => 12
+
+datagram.data[0].value # Returns a binary string
+# => "\x01"
+
+# ...
+
+request = os.action(1, true)
+byte_string = request.to_binary_s
+
+# Send byte_string to KNX BAOS server to execute the request
+# This protocol was designed to be sent over TCP/IP
+
+```
+
+
+## License and copyright
+
+MIT

data/knx.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+    s.name        = "knx"
+    s.version     = '1.0.0'
+    s.authors     = ["Stephen von Takach"]
+    s.email       = ["steve@cotag.me"]
+    s.licenses    = ["MIT"]
+    s.homepage    = "https://github.com/acaprojects/ruby-knx"
+    s.summary     = "KNX protocol on Ruby"
+    s.description = <<-EOF
+        Constructs KNX standard datagrams that make it easy to communicate with devices on KNX networks
+    EOF
+
+
+    s.add_dependency 'bindata', '~> 2.3'
+
+    s.add_development_dependency 'rspec', '~> 3.5'
+    s.add_development_dependency 'yard',  '~> 0'
+    s.add_development_dependency 'rake',  '~> 11'
+
+
+    s.files = Dir["{lib}/**/*"] + %w(knx.gemspec README.md)
+    s.test_files = Dir["spec/**/*"]
+    s.extra_rdoc_files = ["README.md"]
+
+    s.require_paths = ["lib"]
+end

data/lib/knx/address.rb

@@ -0,0 +1,150 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    # ------------------------
+    #    Address Processing
+    # ------------------------
+    #           +-----------------------------------------------+
+    # 16 bits   |              INDIVIDUAL ADDRESS               |
+    #           +-----------------------+-----------------------+
+    #           | OCTET 0 (high byte)   |  OCTET 1 (low byte)   |
+    #           +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+    #    bits   | 7| 6| 5| 4| 3| 2| 1| 0| 7| 6| 5| 4| 3| 2| 1| 0|
+    #           +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+    #           |  Subnetwork Address   |                       |
+    #           +-----------+-----------+     Device Address    |
+    #           |(Area Adrs)|(Line Adrs)|                       |
+    #           +-----------------------+-----------------------+
+
+    #           +-----------------------------------------------+
+    # 16 bits   |             GROUP ADDRESS (3 level)           |
+    #           +-----------------------+-----------------------+
+    #           | OCTET 0 (high byte)   |  OCTET 1 (low byte)   |
+    #           +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+    #    bits   | 7| 6| 5| 4| 3| 2| 1| 0| 7| 6| 5| 4| 3| 2| 1| 0|
+    #           +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+    #           |  | Main Grp  | Midd G |       Sub Group       |
+    #           +--+--------------------+-----------------------+
+
+    #           +-----------------------------------------------+
+    # 16 bits   |             GROUP ADDRESS (2 level)           |
+    #           +-----------------------+-----------------------+
+    #           | OCTET 0 (high byte)   |  OCTET 1 (low byte)   |
+    #           +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+    #    bits   | 7| 6| 5| 4| 3| 2| 1| 0| 7| 6| 5| 4| 3| 2| 1| 0|
+    #           +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+    #           |  | Main Grp  |            Sub Group           |
+    #           +--+--------------------+-----------------------+
+    module Address
+        module ClassMethods
+            def parse(input)
+                address = @address_class.new
+                klass = input.class
+
+                if klass == Array
+                    address.read(input.pack('n'))
+                elsif [Integer, Fixnum].include? klass
+                    address.read([input].pack('n'))
+                elsif klass == String
+                    tmp = parse_friendly(input)
+                    if tmp.nil?
+                        address.read(input)
+                    else
+                        address = tmp
+                    end
+                else
+                    raise 'address parsing failed'
+                end
+
+                address
+            end
+        end
+
+        def self.included(base)
+            base.instance_variable_set(:@address_class, base)
+            base.extend(ClassMethods)
+        end
+
+        def to_i
+            # 16-bit unsigned, network (big-endian)
+            to_binary_s.unpack('n')[0]
+        end
+
+        def is_group?; true; end
+    end
+
+    class GroupAddress < ::BinData::Record
+        include Address
+        endian :big
+
+        bit1 :_reserved_,   value: 0
+        bit4 :main_group
+        bit3 :middle_group
+        uint8 :sub_group
+        
+
+        def to_s
+            "#{main_group}/#{middle_group}/#{sub_group}"
+        end
+
+        def self.parse_friendly(str)
+            result = str.split('/')
+            if result.length == 3
+                address = GroupAddress.new
+                address.main_group   = result[0].to_i
+                address.middle_group = result[1].to_i
+                address.sub_group    = result[2].to_i
+                address
+            end
+        end
+    end
+
+    class GroupAddress2Level < ::BinData::Record
+        include Address
+        endian :big
+
+        bit1  :_reserved_,   value: 0
+        bit4  :main_group
+        bit11 :sub_group
+        
+
+        def to_s
+            "#{main_group}/#{sub_group}"
+        end
+
+        def self.parse_friendly(str)
+            result = str.split('/')
+            if result.length == 2
+                address = GroupAddress2Level.new
+                address.main_group = result[0].to_i
+                address.sub_group = result[1].to_i
+                address
+            end
+        end
+    end
+
+    class IndividualAddress < ::BinData::Record
+        include Address
+        endian :big
+
+        bit4 :area_address
+        bit4 :line_address
+        uint8 :device_address
+        
+        def to_s
+            "#{area_address}.#{line_address}.#{device_address}"
+        end
+
+        def is_group?; false; end
+
+        def self.parse_friendly(str)
+            result = str.split('.')
+            if result.length == 3
+                address = IndividualAddress.new
+                address.area_address = result[0].to_i
+                address.line_address = result[1].to_i
+                address.device_address = result[2].to_i
+            end
+        end
+    end
+end

data/lib/knx/cemi.rb

@@ -0,0 +1,220 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    # APCI type
+    ActionType = {
+        group_read:  0,
+        group_resp:  1,
+        group_write: 2,
+
+        individual_write: 3,
+        individual_read:  4,
+        individual_resp:  5,
+
+        adc_read: 6,
+        adc_resp: 7,
+
+        memory_read:  8,
+        memory_resp:  9,
+        memory_write: 10,
+
+        user_msg: 11,
+
+        descriptor_read: 12,
+        descriptor_resp: 13,
+
+        restart: 14,
+        escape:  15
+    }
+
+    TpciType = {
+        unnumbered_data: 0b00,
+        numbered_data:   0b01,
+        unnumbered_control: 0b10,
+        numbered_control:   0b11
+    }
+
+    MsgCode = {
+        send_datagram: 0x29
+    }
+
+    Priority = {
+        system: 0,
+        alarm: 1,
+        high: 2,
+        low: 3
+    }
+    
+
+    # CEMI == Common External Message Interface
+    # +--------+--------+--------+--------+----------------+----------------+--------+----------------+
+    # |  Msg   |Add.Info| Ctrl 1 | Ctrl 2 | Source Address | Dest. Address  |  Data  |      APDU      |
+    # | Code   | Length |        |        |                |                | Length |                |
+    # +--------+--------+--------+--------+----------------+----------------+--------+----------------+
+    #   1 byte   1 byte   1 byte   1 byte      2 bytes          2 bytes       1 byte      2 bytes
+    #
+    #  Message Code    = 0x11 - a L_Data.req primitive
+    #      COMMON EMI MESSAGE CODES FOR DATA LINK LAYER PRIMITIVES
+    #          FROM NETWORK LAYER TO DATA LINK LAYER
+    #          +---------------------------+--------------+-------------------------+---------------------+------------------+
+    #          | Data Link Layer Primitive | Message Code | Data Link Layer Service | Service Description | Common EMI Frame |
+    #          +---------------------------+--------------+-------------------------+---------------------+------------------+
+    #          |        L_Raw.req          |    0x10      |                         |                     |                  |
+    #          +---------------------------+--------------+-------------------------+---------------------+------------------+
+    #          |                           |              |                         | Primitive used for  | Sample Common    |
+    #          |        L_Data.req         |    0x11      |      Data Service       | transmitting a data | EMI frame        |
+    #          |                           |              |                         | frame               |                  |
+    #          +---------------------------+--------------+-------------------------+---------------------+------------------+
+    #          |        L_Poll_Data.req    |    0x13      |    Poll Data Service    |                     |                  |
+    #          +---------------------------+--------------+-------------------------+---------------------+------------------+
+    #          |        L_Raw.req          |    0x10      |                         |                     |                  |
+    #          +---------------------------+--------------+-------------------------+---------------------+------------------+
+    #          FROM DATA LINK LAYER TO NETWORK LAYER
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          | Data Link Layer Primitive | Message Code | Data Link Layer Service | Service Description |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          |        L_Poll_Data.con    |    0x25      |    Poll Data Service    |                     |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          |                           |              |                         | Primitive used for  |
+    #          |        L_Data.ind         |    0x29      |      Data Service       | receiving a data    |
+    #          |                           |              |                         | frame               |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          |        L_Busmon.ind       |    0x2B      |   Bus Monitor Service   |                     |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          |        L_Raw.ind          |    0x2D      |                         |                     |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          |                           |              |                         | Primitive used for  |
+    #          |                           |              |                         | local confirmation  |
+    #          |        L_Data.con         |    0x2E      |      Data Service       | that a frame was    |
+    #          |                           |              |                         | sent (does not mean |
+    #          |                           |              |                         | successful receive) |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+    #          |        L_Raw.con          |    0x2F      |                         |                     |
+    #          +---------------------------+--------------+-------------------------+---------------------+
+
+    #  Add.Info Length = 0x00 - no additional info
+    #  Control Field 1 = see the bit structure above
+    #  Control Field 2 = see the bit structure above
+    #  Source Address  = 0x0000 - filled in by router/gateway with its source address which is
+    #                    part of the KNX subnet
+    #  Dest. Address   = KNX group or individual address (2 byte)
+    #  Data Length     = Number of bytes of data in the APDU excluding the TPCI/APCI bits
+    #  APDU            = Application Protocol Data Unit - the actual payload including transport
+    #                    protocol control information (TPCI), application protocol control
+    #                    information (APCI) and data passed as an argument from higher layers of
+    #                    the KNX communication stack
+    #
+    class CEMI < BinData::Record
+        endian :big
+        
+        uint8 :msg_code
+        uint8 :info_length
+
+
+        # ---------------------
+        #    Control Fields
+        # ---------------------
+
+        # Bit order
+        # +---+---+---+---+---+---+---+---+
+        # | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
+        # +---+---+---+---+---+---+---+---+
+
+        #  Control Field 1
+
+        #   Bit  |
+        #  ------+---------------------------------------------------------------
+        #    7   | Frame Type  - 0x0 for extended frame
+        #        |               0x1 for standard frame
+        #  ------+---------------------------------------------------------------
+        #    6   | Reserved
+        #        |
+        #  ------+---------------------------------------------------------------
+        #    5   | Repeat Flag - 0x0 repeat frame on medium in case of an error
+        #        |               0x1 do not repeat
+        #  ------+---------------------------------------------------------------
+        #    4   | System Broadcast - 0x0 system broadcast
+        #        |                    0x1 broadcast
+        #  ------+---------------------------------------------------------------
+        #    3   | Priority    - 0x0 system
+        #        |               0x1 normal (also called alarm priority)
+        #  ------+               0x2 urgent (also called high priority)
+        #    2   |               0x3 low
+        #        |
+        #  ------+---------------------------------------------------------------
+        #    1   | Acknowledge Request - 0x0 no ACK requested
+        #        | (L_Data.req)          0x1 ACK requested
+        #  ------+---------------------------------------------------------------
+        #    0   | Confirm      - 0x0 no error
+        #        | (L_Data.con) - 0x1 error
+        #  ------+---------------------------------------------------------------
+        bit1  :is_standard_frame
+        bit1  :_reserved_,   value: 0
+        bit1  :no_repeat
+        bit1  :broadcast
+        bit2  :priority     # 2 bits
+        bit1  :ack_requested
+        bit1  :is_error
+
+        #  Control Field 2
+
+        #   Bit  |
+        #  ------+---------------------------------------------------------------
+        #    7   | Destination Address Type - 0x0 individual address
+        #        |                          - 0x1 group address
+        #  ------+---------------------------------------------------------------
+        #   6-4  | Hop Count (0-7)
+        #  ------+---------------------------------------------------------------
+        #   3-0  | Extended Frame Format - 0x0 standard frame
+        #  ------+---------------------------------------------------------------
+        bit1  :is_group_address
+        bit3  :hop_count
+        bit4  :extended_frame_format
+
+        uint16 :source_address
+        uint16 :destination_address
+
+        uint8 :data_length
+
+
+        # In the Common EMI frame, the APDU payload is defined as follows:
+
+        # +--------+--------+--------+--------+--------+
+        # | TPCI + | APCI + |  Data  |  Data  |  Data  |
+        # |  APCI  |  Data  |        |        |        |
+        # +--------+--------+--------+--------+--------+
+        #   byte 1   byte 2  byte 3     ...     byte 16
+
+        # For data that is 6 bits or less in length, only the first two bytes are used in a Common EMI
+        # frame. Common EMI frame also carries the information of the expected length of the Protocol
+        # Data Unit (PDU). Data payload can be at most 14 bytes long.  <p>
+
+        # The first byte is a combination of transport layer control information (TPCI) and application
+        # layer control information (APCI). First 6 bits are dedicated for TPCI while the two least
+        # significant bits of first byte hold the two most significant bits of APCI field, as follows:
+
+        #   Bit 1    Bit 2    Bit 3    Bit 4    Bit 5    Bit 6    Bit 7    Bit 8      Bit 1   Bit 2
+        # +--------+--------+--------+--------+--------+--------+--------+--------++--------+----....
+        # |        |        |        |        |        |        |        |        ||        |
+        # |  TPCI  |  TPCI  |  TPCI  |  TPCI  |  TPCI  |  TPCI  | APCI   |  APCI  ||  APCI  |
+        # |        |        |        |        |        |        |(bit 1) |(bit 2) ||(bit 3) |
+        # +--------+--------+--------+--------+--------+--------+--------+--------++--------+----....
+        # +                            B  Y  T  E    1                            ||       B Y T E  2
+        # +-----------------------------------------------------------------------++-------------....
+
+        # Total number of APCI control bits can be either 4 or 10. The second byte bit structure is as follows:
+
+        #   Bit 1    Bit 2    Bit 3    Bit 4    Bit 5    Bit 6    Bit 7    Bit 8      Bit 1   Bit 2
+        # +--------+--------+--------+--------+--------+--------+--------+--------++--------+----....
+        # |        |        |        |        |        |        |        |        ||        |
+        # |  APCI  |  APCI  | APCI/  |  APCI/ |  APCI/ |  APCI/ | APCI/  |  APCI/ ||  Data  |  Data
+        # |(bit 3) |(bit 4) | Data   |  Data  |  Data  |  Data  | Data   |  Data  ||        |
+        # +--------+--------+--------+--------+--------+--------+--------+--------++--------+----....
+        # +                            B  Y  T  E    2                            ||       B Y T E  3
+        # +-----------------------------------------------------------------------++-------------....
+        bit2 :tpci # transport protocol control information
+        bit4 :tpci_seq_num # Sequence number when tpci is sequenced
+        bit4 :apci # application protocol control information (What we trying to do: Read, write, respond etc)
+        bit6 :data # Or the tail end of APCI depending on the message type
+    end
+end

data/lib/knx/datagram.rb

@@ -0,0 +1,150 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    DatagramBuilder = Struct.new(:header, :cemi, :source_address, :destination_address, :data) do
+
+        def to_binary_s
+            data_array = self.data
+
+            resp = if present? data_array
+                @cemi.data_length = data_array.length
+
+                if data_array[0] <= 0b111111
+                    @cemi.data = data_array[0]
+                    if data_array.length > 1
+                        data_array[1..-1].pack('C')
+                    else
+                        String.new
+                    end
+                else
+                    @cemi.data = 0
+                    data_array.pack('C')
+                end
+            else
+                @cemi.data = 0
+                @cemi.data_length = 0
+                String.new
+            end
+
+            @cemi.source_address      = self.source_address.to_i
+            @cemi.destination_address = self.destination_address.to_i
+
+            # 17 == header + cemi
+            @header.request_length = resp.bytesize + 17
+            "#{@header.to_binary_s}#{@cemi.to_binary_s}#{resp}"
+        end
+
+
+        protected
+
+
+        def present?(data)
+            !(data.nil? || data.empty?)
+        end
+
+        def initialize(address = nil, options = nil)
+            super()
+            return unless address
+
+            @address = parse(address)
+
+            @cemi = CEMI.new
+            @cemi.msg_code = MsgCode[options[:msg_code]]
+            @cemi.is_standard_frame = true
+            @cemi.no_repeat = options[:no_repeat]
+            @cemi.broadcast = options[:broadcast]
+            @cemi.priority = Priority[options[:priority]]
+
+            @cemi.is_group_address = @address.is_group?
+            @cemi.hop_count = options[:hop_count]
+
+            @header = Header.new
+            if options[:request_type]
+                @header.request_type = RequestTypes[options[:request_type]]
+            else
+                @header.request_type = RequestTypes[:routing_indication]
+            end
+
+            self.header = @header
+            self.cemi = @cemi
+            self.source_address = IndividualAddress.parse_friendly('0.0.1')
+            self.destination_address = @address
+
+            @cemi.source_address      = self.source_address.to_i
+            @cemi.destination_address = self.destination_address.to_i
+        end
+
+        def parse(address)
+            result = address.split('/')
+            if result.length > 1
+                if result.length == 3
+                    GroupAddress.parse_friendly(address)
+                else
+                    GroupAddress2Level.parse_friendly(address)
+                end
+            else
+                IndividualAddress.parse_friendly(address)
+            end
+        end
+    end
+
+    class ActionDatagram < DatagramBuilder
+        def initialize(address, data_array, options)
+            super(address, options)
+
+            # Set the protocol control information
+            @cemi.apci = @address.is_group? ? ActionType[:group_write] : ActionType[:individual_write]
+            @cemi.tpci = TpciType[:unnumbered_data]
+
+            # To attempt save a byte we try to cram the first byte into the APCI field
+            if present? data_array
+                if data_array[0] <= 0b111111
+                    @cemi.data = data_array[0]
+                end
+                
+                @cemi.data_length = data_array.length
+                self.data = data_array
+            end
+        end
+    end
+
+    class StatusDatagram < DatagramBuilder
+        def initialize(address, options)
+            super(address, options)
+
+            # Set the protocol control information
+            @cemi.apci = @address.is_group? ? ActionType[:group_read] : ActionType[:individual_read]
+            @cemi.tpci = TpciType[:unnumbered_data]
+        end
+    end
+
+    class ResponseDatagram < DatagramBuilder
+        def initialize(raw_data, options)
+            super()
+
+            @header = Header.new
+            @header.read(raw_data[0..5])
+
+            @cemi = CEMI.new
+            @cemi.read(raw_data[6..16])
+
+            self.header = @header
+            self.cemi = @cemi
+
+            self.data = raw_data[17..(@header.request_length - 1)].bytes
+            if @cemi.data_length > self.data.length
+                self.data.unshift @cemi.data
+            end
+
+            self.source_address = IndividualAddress.parse(@cemi.source_address.to_i)
+
+            if @cemi.is_group_address == 0
+                self.destination_address = IndividualAddress.parse(@cemi.destination_address.to_i)
+            elsif options[:two_level_group]
+                self.destination_address = GroupAddress2Level.parse(@cemi.destination_address.to_i)
+            else
+                self.destination_address = GroupAddress.parse(@cemi.destination_address.to_i)
+            end
+        end
+    end
+end

data/lib/knx/header.rb

@@ -0,0 +1,32 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    RequestTypes = {
+        search_request: 0x0201,
+        search_response: 0x0202,
+        description_request: 0x0203,
+        description_response: 0x0204,
+        connect_request: 0x0205,
+        connect_response: 0x0206,
+        connectionstate_request: 0x0207,
+        connectionstate_response: 0x0208,
+        disconnect_request: 0x0209,
+        disconnect_response: 0x020A,
+        device_configuration_request: 0x0310,
+        device_configuration_ack: 0x0311,
+        tunnelling_request: 0x0420,
+        tunnelling_ack: 0x0421,
+        routing_indication: 0x0530,
+        routing_lost_message: 0x0531
+    }
+
+    # http://www.openremote.org/display/forums/KNX+IP+Connection+Headers
+    class Header < BinData::Record
+        endian :big
+
+        uint8  :header_length,  value: 0x06  # Length 6 (always for version 1)
+        uint8  :version,        value: 0x10  # Version 1
+        uint16 :request_type
+        uint16 :request_length
+    end
+end

data/lib/knx/object_server/datagram.rb

@@ -0,0 +1,98 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    class ObjectServer
+        Errors = {
+            0 => :no_error,
+            1 => :device_internal_error,
+            2 => :no_item_found,
+            3 => :buffer_is_too_small,
+            4 => :item_not_writeable,
+            5 => :service_not_supported,
+            6 => :bad_service_param,
+            7 => :wrong_datapoint_id,
+            8 => :bad_datapoint_command,
+            9 => :bad_datapoint_length,
+            10 => :message_inconsistent,
+            11 => :object_server_busy
+        }
+
+        Datagram = Struct.new(:knx_header, :connection, :header) do
+            def initialize(raw_data = nil)
+                super(Header.new, ConnectionHeader.new, ObjectHeader.new)
+                # These values are unique to the KNX Object Server
+                self.knx_header.version = 0x20
+                self.knx_header.request_type = 0xF080
+                @data = []
+
+                if raw_data
+                    self.knx_header.read(raw_data[0..5])
+                    self.connection.read(raw_data[6..9])
+                    self.header.read(raw_data[10..15])
+
+                    # Check for error
+                    if self.header.item_count == 0
+                        @error_code = raw_data[16].getbyte(0)
+                        @error = Errors[@error_code]
+                    else
+                        @error_code = 0
+                        @error = :no_error
+
+                        # Read the response
+                        index = 16
+                        self.header.item_count.times do
+                            next_index = index + 4
+                            item = StatusItem.new
+                            item.read(raw_data[index...next_index])
+
+                            index = next_index + item.value_length
+                            item.value = raw_data[next_index...index]
+
+                            @data << item
+                        end
+                    end
+                end
+            end
+
+
+            attr_reader :error, :error_code, :data
+
+
+            def error?
+                @error_code != 0
+            end
+
+            def to_binary_s
+                self.header.item_count = @data.length if @data.length > 0
+                resp = "#{self.connection.to_binary_s}#{self.header.to_binary_s}"
+
+                @data.each do |item|
+                    resp << item.to_binary_s
+                end
+
+                self.knx_header.request_length = resp.length + 6
+                "#{self.knx_header.to_binary_s}#{resp}"
+            end
+
+            def add_action(index, data: nil, **options)
+                req = RequestItem.new
+                req.id = index.to_i
+                req.command = Commands[options[:command]] || :set_value
+                if not data.nil?
+                    if data == true || data == false
+                        data = data ? 1 : 0
+                    end
+
+                    if data.is_a? String
+                        req.value = data
+                    else
+                        req.value = ''
+                        req.value << data
+                    end
+                end
+                @data << req
+                self
+            end
+        end
+    end
+end

data/lib/knx/object_server/object_header.rb

@@ -0,0 +1,39 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    class ObjectServer
+        class ConnectionHeader < BinData::Record
+            endian :big
+
+            uint8  :header_length,  value: 0x04
+            uint8  :reserved1,      value: 0x00
+            uint8  :reserved2,      value: 0x00
+            uint8  :reserved3,      value: 0x00
+        end
+
+
+        Filters = {
+            0 => :all_values,
+            1 => :valid_values,
+            2 => :updated_values
+        }
+        Filters.merge!(Filters.invert)
+
+        class ObjectHeader < BinData::Record
+            endian :big
+
+            uint8  :main_service, value: 0xF0
+            uint8  :sub_service
+            uint16 :start_item
+            uint16 :item_count
+
+            attr_accessor :filter
+
+            def to_binary_s
+                resp = super()
+                resp << @filter if @filter
+                resp
+            end
+        end
+    end
+end

data/lib/knx/object_server/request_item.rb

@@ -0,0 +1,33 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    class ObjectServer
+        Commands = {
+            0 => :no_command,
+            1 => :set_value,
+            2 => :send_value,
+            3 => :set_value_and_send,
+            4 => :read_value,
+            5 => :clear_transmission_state
+        }
+        Commands.merge!(Commands.invert)
+
+        class RequestItem < BinData::Record
+            endian :big
+
+            uint16 :id
+            bit4   :reserved
+            bit4   :command
+            uint8  :value_length
+
+
+            attr_accessor :value
+
+
+            def to_binary_s
+                self.value_length = @value ? @value.length : 0
+                "#{super()}#{@value}"
+            end
+        end
+    end
+end

data/lib/knx/object_server/status_item.rb

@@ -0,0 +1,39 @@
+#encoding: ASCII-8BIT
+
+class KNX
+    class ObjectServer
+        Status = {
+            0 => :idle_ok,
+            1 => :idle_error,
+            2 => :transmission_in_progress,
+            3 => :transmission_request
+        }
+
+        class StatusItem < BinData::Record
+            endian :big
+
+            uint16 :id
+
+            bit3   :reserved
+            bit1   :valid
+            bit1   :update_from_bus
+            bit1   :data_request
+            bit2   :status
+
+            uint8  :value_length
+
+
+            attr_accessor :value
+
+
+            def to_binary_s
+                self.value_length = @value ? @value.length : 0
+                "#{super()}#{@value}"
+            end
+
+            def transmission_status
+                ::KNX::ObjectServer::Status[self.status]
+            end
+        end
+    end
+end

data/lib/knx/object_server.rb

@@ -0,0 +1,62 @@
+#encoding: ASCII-8BIT
+
+require 'bindata'
+
+require 'knx/header'
+require 'knx/object_server/object_header'
+require 'knx/object_server/status_item'
+require 'knx/object_server/request_item'
+require 'knx/object_server/datagram'
+
+
+class KNX
+    class ObjectServer
+        Defaults = {
+            filter: :valid_values,
+            item_count: 1,
+            command: :set_value_and_send
+        }
+
+        def initialize(options = {})
+            @options = Defaults.merge(options)
+        end
+
+        # Builds an Object Server command datagram for setting an index to a value
+        #
+        # @param index [Integer, Fixnum] the object address or index as defined in the object server
+        # @param data [String, Integer, Fixnum, Array<Integer, Fixnum>] the value to be set at the address
+        # @return [Datagram] a ruby object representing the request that can be modified further
+        def action(index, data = nil, **options)
+            options = @options.merge(options)
+
+            cmd = Datagram.new
+            cmd.add_action(index.to_i, data: data, **options)
+            cmd.header.sub_service = 0x06
+            cmd.header.start_item = index.to_i
+            cmd
+        end
+
+        # Builds an Object Server request datagram for querying an index value
+        #
+        # @param index [Integer, Fixnum] the object address or index as defined in the object server
+        # @return [Datagram] a ruby object representing the request that can be modified further
+        def status(index, options = {})
+            options = @options.merge(options)
+
+            data = Datagram.new
+            data.header.sub_service = 0x05
+            data.header.start_item = index.to_i
+            data.header.item_count = options[:item_count].to_i
+            data.header.filter = Filters[options[:filter]]
+            data
+        end
+
+        # Returns a KNX Object Server datagram as a ruby object for easy inspection
+        #
+        # @param data [String] a binary string containing the datagram
+        # @return [Datagram] a ruby object representing the data
+        def read(raw_data)
+            Datagram.new(raw_data)
+        end
+    end
+end

data/lib/knx.rb

@@ -0,0 +1,66 @@
+#encoding: ASCII-8BIT
+
+require 'bindata'
+
+require 'knx/header'
+require 'knx/cemi'
+require 'knx/address'
+require 'knx/datagram'
+
+
+class KNX
+    Defaults = {
+        priority: :low,
+        no_repeat: true,
+        broadcast: true,
+        hop_count: 6,
+        msg_code: :send_datagram
+    }
+
+    def initialize(options = {})
+        @options = Defaults.merge(options)
+    end
+
+    # Builds a KNX command datagram for setting an address to a value
+    #
+    # @param address [String] the object address in group or individual format
+    # @param data [String, Integer, Fixnum, Array<Integer, Fixnum>] the value to be set at the address
+    # @return [ActionDatagram] a ruby object representing the request that can be modified further
+    def action(address, data, options = {})
+        if data == true || data == false
+            data = data ? 1 : 0
+        end
+
+        klass = data.class
+
+        raw = if klass == String
+            data.bytes
+        elsif [Integer, Fixnum].include? klass
+            # Assume this is a byte
+            [data]
+        elsif klass == Array
+            # We assume this is a byte array
+            data
+        else
+            raise ArgumentError, "Unknown data type for #{data}"
+        end
+
+        ActionDatagram.new(address, raw, @options.merge(options))
+    end
+
+    # Builds a KNX status request datagram for querying an address value
+    #
+    # @param address [String] the object address in group or individual format
+    # @return [StatusDatagram] a ruby object representing the request that can be modified further
+    def status(address, options = {})
+        StatusDatagram.new(address, @options.merge(options))
+    end
+
+    # Represents a KNX datagram as a ruby object for easy inspection
+    #
+    # @param data [String] a binary string containing the datagram
+    # @return [ResponseDatagram] a ruby object representing the data
+    def read(data, options = {})
+        ResponseDatagram.new(data, @options.merge(options))
+    end
+end

data/spec/knx_spec.rb

@@ -0,0 +1,38 @@
+#encoding: ASCII-8BIT
+
+require 'knx'
+
+
+describe "knx protocol helper" do
+    before :each do
+        @knx = KNX.new
+    end
+
+    it "should parse and generate the same string" do
+        datagram = @knx.read("\x06\x10\x05\x30\0\x11\x29\0\xbc\xe0\0\x01\x0a\0\x01\0\x80")
+        expect(datagram.to_binary_s).to eq("\x06\x10\x05\x30\0\x11\x29\0\xbc\xe0\0\x01\x0a\0\x01\0\x80")
+
+        datagram = @knx.read("\x06\x10\x05\x30\0\x11\x29\0\xbc\xe0\0\x01\x0a\0\x01\0\x81")
+        expect(datagram.to_binary_s).to eq("\x06\x10\x05\x30\0\x11\x29\0\xbc\xe0\0\x01\x0a\0\x01\0\x81")
+
+        expect(datagram.data).to eq([1])
+        expect(datagram.source_address.to_s).to eq("0.0.1")
+        expect(datagram.destination_address.to_s).to eq("1/2/0")
+    end
+
+    it "should generate single bit action requests" do
+        datagram = @knx.action('1/2/0', false)
+        expect(datagram.to_binary_s).to eq("\x06\x10\x05\x30\0\x11\x29\0\xbc\xe0\0\x01\x0a\0\x01\0\x80")
+
+        datagram = @knx.action('1/2/0', true)
+        expect(datagram.to_binary_s).to eq("\x06\x10\x05\x30\0\x11\x29\0\xbc\xe0\0\x01\x0a\0\x01\0\x81")
+    end
+
+    it "should generate byte action requests" do
+        datagram = @knx.action('1/2/0', 20)
+        expect(datagram.to_binary_s).to eq("\x06\x10\x050\x00\x11)\x00\xBC\xE0\x00\x01\n\x00\x01\x00\x94")
+
+        datagram = @knx.action('1/2/0', 240)
+        expect(datagram.to_binary_s).to eq("\x06\x10\x050\x00\x12)\x00\xBC\xE0\x00\x01\n\x00\x01\x00\x80\xF0")
+    end
+end

data/spec/object_server_spec.rb

@@ -0,0 +1,34 @@
+#encoding: ASCII-8BIT
+
+require 'knx/object_server'
+
+
+describe "object server protocol helper" do
+    before :each do
+        @knx = KNX::ObjectServer.new
+    end
+
+    it "should parse and generate the same string" do
+        datagram = @knx.read("\x06\x10\xF0\x80\x00\x15\x04\x00\x00\x00\xF0\x06\x00\x02\x00\x01\x00\x02\x03\x01\x01")
+        expect(datagram.to_binary_s).to eq("\x06\x10\xF0\x80\x00\x15\x04\x00\x00\x00\xF0\x06\x00\x02\x00\x01\x00\x02\x03\x01\x01")
+
+        expect(datagram.data[0].id).to eq(2)
+        expect(datagram.data[0].value).to eq("\x01")
+    end
+
+    it "should generate single bit action requests" do
+        datagram = @knx.action(1, false)
+        expect(datagram.to_binary_s).to eq("\x06\x10\xF0\x80\x00\x15\x04\x00\x00\x00\xF0\x06\x00\x01\x00\x01\x00\x01\x03\x01\x00")
+
+        datagram = @knx.action(2, true)
+        expect(datagram.to_binary_s).to eq("\x06\x10\xF0\x80\x00\x15\x04\x00\x00\x00\xF0\x06\x00\x02\x00\x01\x00\x02\x03\x01\x01")
+    end
+
+    it "should generate byte action requests" do
+        datagram = @knx.action(3, 20)
+        expect(datagram.to_binary_s).to eq("\x06\x10\xF0\x80\x00\x15\x04\x00\x00\x00\xF0\x06\x00\x03\x00\x01\x00\x03\x03\x01\x14")
+
+        datagram = @knx.action(4, 240)
+        expect(datagram.to_binary_s).to eq("\x06\x10\xF0\x80\x00\x15\x04\x00\x00\x00\xF0\x06\x00\x04\x00\x01\x00\x04\x03\x01\xF0")
+    end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: knx
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Stephen von Takach
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bindata
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11'
+description: "        Constructs KNX standard datagrams that make it easy to communicate
+  with devices on KNX networks\n"
+email:
+- steve@cotag.me
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- knx.gemspec
+- lib/knx.rb
+- lib/knx/address.rb
+- lib/knx/cemi.rb
+- lib/knx/datagram.rb
+- lib/knx/header.rb
+- lib/knx/object_server.rb
+- lib/knx/object_server/datagram.rb
+- lib/knx/object_server/object_header.rb
+- lib/knx/object_server/request_item.rb
+- lib/knx/object_server/status_item.rb
+- spec/knx_spec.rb
+- spec/object_server_spec.rb
+homepage: https://github.com/acaprojects/ruby-knx
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: KNX protocol on Ruby
+test_files:
+- spec/knx_spec.rb
+- spec/object_server_spec.rb
+has_rdoc: