gm3156 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15bff36286b3a2400520c9c60c84127385383c6c1ec0de527623d293e8ddafae
+  data.tar.gz: 67484565194ee5906d774ed712693f16c064b5b10fd789421b5d29dc6c0bbb96
+SHA512:
+  metadata.gz: 2dda4bbb3f0ab63ef8cd6418c80b9bd1ccfbf9afe2286624aa2ec391cb7a9a8387f5c1e2236be567c4df92b380139079e989e7c95958ae799230330eb80ce6e1
+  data.tar.gz: f1192b16b8ca6d3fbc6003d2af7776a96f65e38c3bda37d74018d075729ea65eb0b0c27014ffa4e107a54ec46adfd5eb04571d46adc3266702cdbd3065a9cdf7

data/PROTOCOL.md

@@ -0,0 +1,76 @@
+# GM1356 digital sound level meter USB protocol description
+
+## Interface description
+
+Interface is recognised as a **HID** with **two endpoints**. One **in** and one **out**. Both work via **URB interruptions** with **8 bytes packet data length**.
+
+## Ask for current state
+
+To ask for current state, send `URB_INTERRUPT out` to endpoint **2** with capture data `b3[random_magic_id]:24bits]00000000`. Then you will receive `URB_INTERRUPT in` from endpoint **1** with data described below.
+
+It looks that SoundLab generates some random (or not random) id per each instance of application. First I tried to use exactly the same requests in my driver and I received no response. It means the device has to store it somewhere and prevents from using it again. No idea why. After generating `random_magic_id` it started working. 
+
+You can use the same `random_magic_id` per instance of your application as SoundLab do. 
+
+###example capture data
+``
+
+## Decode current state
+
+`URB_INTERRUPT in` have leftover capture data with this structure:
+`[value:16bits][settings:4bits][range:4bits][unknown:40bits]` - 64bits
+
+### Decode sound level `value`
+Convert 16bits to decimal, then add point before last digit.
+
+### Decode `settings`
+Settings have this structure:
+`[unused:1bit][slow/fast mode:1bit][max mode:1bit][a/c filter:1bit]` - 4 bits
+
+```
+a, not max, slow  |   0
+c, not max, slow  |   1
+a, max, slow      |   2
+c, max, slow      |   3
+a, not max, fast  |   4
+c, not max, fast  |   5
+a, max, fast      |   6
+c, max, fast      |   7
+```
+
+### Decode `range`
+Convert 4bits to decimal. Use decimal to assign corresponding range.
+
+```
+30-130  |   0
+30-60   |   1
+50-100  |   2
+60-110  |   3
+80-130  |   4
+```
+
+### Example
+#### data:
+`0292749b90ddc0ff`
+#### meaning:
+ * `value`: 
+   * `0292` is `658` decimal, add point before last digit and it is `65.8`dB
+ * `settings`:
+   * `7` is `0111` binary, so it is `fast mode`, `max mode`, `filter c` 
+ * `range`:
+   * `4` means `80-130`dB range
+
+## Change settings and range
+
+To change settings send `INTERRUPT out` to endpoint **2** with such format:
+
+### Data format
+`56[settings:4bits][range:4bits]000000000000`
+
+`settings` and `range` are the same as described in previous section.
+
+### Example
+#### data:
+`5621000000000000`
+#### meaning:
+Set state to `a filter`, `max mode`, `slow mode` with `30-60`dB range.

data/README.md

@@ -0,0 +1,38 @@
+# GM1356 for Linux
+
+## Description
+This driver was written for **Digital Sound Level Meter** with USB (type **GM1356**) serial number: `HA:1303162` ordered from China via Aliexpress. My sonometer works with **SoundLab** `Sound Level Meter v. 1.0.0.20, build 2016-07-20` delivered by [Benetech Poland](https://benetech-poland.pl/) (thank you very much for this). I was trying to run it with SoundLab downloaded from Bogen website, but it couldn't connect to the device. It means my driver may not work with some GM1356 devices.
+
+## Installation
+After cloning this git repository make sure you have `ruby` interpretter and `bundler` gem. Then go to the main directory and run:
+
+```bundle install```
+
+Now make sure that your `users` have access to your device. In my case I had to create `/etc/udev/rules.d/90-usbpermission.rules` with such content:
+
+```SUBSYSTEMS=="usb",ATTRS{idProduct}=="74e3",ATTRS{idVendor}=="64bd",GROUP="users",MODE="0666"```
+
+Then run:
+
+```sudo udevadm control --reload```
+
+And after all reconnect your device if it was already connected.
+
+## Usage
+If you want to print real time data from your sonometer, run:
+
+```./bin/gm3156```
+
+For more options:
+
+```./bin/gm3156 --help```
+
+## Protocol
+I used Wireshark with USBPcap to sniff communication between my device and SoundLab on Windows in order to understend the protocol. Protocol is described in [PROTOCOL.md](PROTOCOL.md).
+
+## Supported functionalities
+* receiving real time data with `sound level value`, `A/C filter`, `max mode`, `slow/fast mode` and `measured range`
+* changing `A/C filter`, `max mode`, `slow/fast mode` and `measured range`
+
+## Unsupported functionalities
+* importing recorded data

data/TODO.md

@@ -0,0 +1,7 @@
+* figure out why some packets are invalid and handle it properly instead of retrying
+* add editing settings feature
+* write help for `./bin/gm3156`
+* write api documentation
+* create gem
+* handle reconnecting device / unconnected device etc. exceptions
+* test if it's stable

data/bin/gm3156

@@ -0,0 +1,51 @@
+#!ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative '../lib/gm3156'
+
+options = {}
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: gm3156 [options]'
+
+  opts.on('-fFILTER', '--filter=FILTER', String, 'A/C filter') do |f|
+    options[:filter] = :a if f.downcase == 'a'
+    options[:filter] = :c if f.downcase == 'c'
+  end
+
+  opts.on('-sSPEED', '--speed=SPEED', String, 'SLOW/FAST mode') do |s|
+    options[:speed] = :slow if ['slow', 's'].include? s.downcase
+    options[:speed] = :fast if ['fast', 'f'].include? s.downcase
+  end
+
+  opts.on('-mBOOLEAN', '--max=BOOLEAN', TrueClass, 'enable/disable MAX mode') do |m|
+    options[:max_mode] = m
+  end
+
+  opts.on('-rINTEGER', '--range=INTEGER', Integer, 'measured levels range ') do |l|
+    options[:max_mode] = l if (0..4).include? l
+  end
+
+  opts.on('--just-set', TrueClass, 'just set options and exit') do
+    options[:just_set] = true
+  end
+
+  opts.on("-h", "--help", "Prints this help") do
+    puts opts
+    exit
+  end
+end.parse!
+
+device = GM3156::Device.new(options)
+
+begin
+  device.read do |record|
+    puts record.to_s
+  end
+rescue Exception # rubocop:disable Lint/RescueException
+  device.close
+  raise
+end unless options[:just_set]
+
+device.close

data/lib/gm3156.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GM3156
+  require_relative 'gm3156/errors'
+  require_relative 'gm3156/device'
+  require_relative 'gm3156/record'
+end

data/lib/gm3156/device.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module GM3156
+  require 'hidapi'
+  require_relative 'errors'
+  require_relative 'settings'
+  require_relative 'record'
+
+  class Device
+    STATE_REQUEST = [0xb3, Random.rand(256), Random.rand(256), Random.rand(256), 0, 0, 0, 0].pack('C*')
+
+    def initialize(vendor_id = 0x64bd, product_id = 0x74e3, **args)
+      self.vendor_id = vendor_id
+      self.product_id = product_id
+      self.device = HIDAPI.open(vendor_id, product_id)
+      read_current_state
+      set_settings(**args) unless args.empty?
+    end
+
+    def close
+      device.close
+    end
+
+    def read(&block)
+      loop do
+        Thread.new do
+          read_current_state(&block)
+        end
+        sleep settings.speed == :fast? ? 0.5 : 1
+      end
+    end
+
+    def set_settings(**args)
+      args.each do |name, value|
+        settings.send("#{name}=", value) if settings.respond_to?("#{name}=")
+      end
+      data = [0x56, settings.pack, 0, 0, 0, 0, 0, 0].pack('C*')
+
+      device.write(data)
+      read_cap_data
+      sleep(0.1)
+    end
+
+    private
+
+    def read_current_state(&block)
+      begin
+        send_state_request
+        data = read_cap_data
+
+        raise InvalidCaptureDataLengthError.new('Capture data should have 8 bytes.', data) if data.length != 8
+
+        record = Record.new(data.unpack('H*').first)
+        self.settings = record.settings
+        block_given? ? block.call(record) : record
+      rescue InvalidCaptureDataLengthError
+        sleep 0.1
+        retry
+      end
+    end
+
+    def send_state_request
+      device.write(STATE_REQUEST)
+    end
+
+    def read_cap_data
+      cap_data = nil
+      cap_data = device.read_timeout(1000) until cap_data && !cap_data.empty?
+      cap_data
+    end
+
+    attr_accessor :vendor_id, :product_id, :device, :settings
+  end
+end

data/lib/gm3156/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module GM3156
+  class InvalidCaptureDataLengthError < StandardError
+    attr_reader :data
+
+    def initialize(msg, data)
+      @data = data
+      super(msg)
+    end
+  end
+end

data/lib/gm3156/record.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GM3156
+  require_relative 'settings'
+
+  class Record
+    def initialize(message)
+      self.timestamp = Time.now
+      self.spl = extract_spl(message)
+      self.settings = Settings.new(message)
+    end
+
+    def extract_spl(message)
+      message[0..3].to_i(16).to_s.insert(-2, '.').to_f
+    end
+
+    def to_s
+      output = "#{timestamp.strftime('%H:%M:%S')} \t SPL: #{spl}dB#{settings.filter.to_s.capitalize}"
+      output += "\t MAX mode" if settings.max_mode
+      output
+    end
+
+    attr_reader :timestamp, :spl, :settings
+
+    private
+
+    attr_writer :timestamp, :spl, :settings
+  end
+end

data/lib/gm3156/settings.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GM3156
+  class Settings
+    AVAILABLE_RANGES = [
+      '30-120',
+      '30-60',
+      '50-100',
+      '60-110',
+      '80-130'
+    ]
+
+    def initialize(message)
+      assign_settings(message)
+    end
+
+    def assign_settings(message)
+      binary_settings = message[4].unpack('b4*').first.chars.map { |c| c.to_i == 1 }
+      self.filter = binary_settings[0] ? :c : :a
+      self.max_mode = binary_settings[1]
+      self.speed = binary_settings[2] ? :fast : :slow
+      self.range = message[5].to_i
+    end
+
+    def pack
+      filter_bit = filter == :c ? 1 : 0
+      max_mode_bit = max_mode ? 1 : 0
+      speed_bit = speed == :fast ? 1 : 0
+
+      boolean_options = "0#{speed_bit}#{max_mode_bit}#{filter_bit}".to_i(2)
+      "#{boolean_options}#{range}".to_i(16)
+    end
+
+    attr_accessor :filter, :max_mode, :speed, :range
+
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: gm3156
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Maciej Ciemborowicz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-05-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hidapi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.9
+description: Digital Sound Level Meter Gm1356 USB driver for Linux.
+email: maciej.ciemborowicz+rubygems@gmail.com
+executables:
+- gm3156
+extensions: []
+extra_rdoc_files: []
+files:
+- PROTOCOL.md
+- README.md
+- TODO.md
+- bin/gm3156
+- lib/gm3156.rb
+- lib/gm3156/device.rb
+- lib/gm3156/errors.rb
+- lib/gm3156/record.rb
+- lib/gm3156/settings.rb
+homepage: https://github.com/ciembor/gm1356
+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: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Captures and prints data, supports editing settings.
+test_files: []