syncsign 0.2.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ec8ce97ef1f4882420617de3310d74e2d4a3783a4f1922847c706c3eb04b13c
-  data.tar.gz: 0a867fa0debe259b37d347aff38800f9ae589a4e2afde253d69fbe2f2cab4bbe
+  metadata.gz: 4574f4a41e361efb3c930e259b9bd99ffba55989fb6d0a314fed51d8d93c5a56
+  data.tar.gz: 890c60254cd507474fc13de8a163c131385b9f38c5408b16e37f92e680668fd7
 SHA512:
-  metadata.gz: fc9cc2483763d6a35cee7d3c9370b2abe6774b5870321ec219ed02c26b61a0d60378c8a38149507bcef9e4cecbb6b88f9a4888e888732d7d47516d6597ab4d3b
-  data.tar.gz: 9bba6acf10f9b33d4a9d11065e12ae6c3d4270bc95e991e03651aace8dd0c52655fe07ea628f110572a0b58b6fce7ca51601dcf48d43cd30308b574b5b165de9
+  metadata.gz: 033cfd91cc3e501b61e8ef2e27028728b174c614b19a8ad2f2d60cc98489e261942773a2fba702a18a3725e6ac3caeb441c94da5eaa400d3a5a2f4ac745df5d1
+  data.tar.gz: 5daf0bead45f71423ca9d7b8b58549a26b2fb02ea6f1373ea235f5e83eb00cb53b1509b457553f64595a7855be25f19baec825ebc75d2a44cef0914d88a3424a

data/README.md

@@ -5,14 +5,13 @@
 Ruby class/gem to access the [SyncSign](http://sync-sign.com) cloud service to display information on e-paper displays.
 
 ## Features
- * Display circles, lines, rectangles, QR codes, and text on the displays.
+ * Display circles, lines, rectangles, QR codes, symbols, text, and more on the displays.
  * Obtain information about associated hubs and displays.
 
 ## TODO
  * Support non-display nodes that connect to the SyncSign hub (like temperature or occupancy sensors)
  * Support display-resident images (item type IMAGE)
  * Support bitmap images from a URI (item type BITMAP\_URI)
- * Support icons in text boxes
 
 ## Use
 
@@ -29,10 +28,27 @@ Create a SyncSign Service instance using your API key (found in the SyncSign por
     template = SyncSign::Template.new(items: items)
     node.render(template: template)
 
+## Direct Rendering
+The SyncSign hubs have a simplified API that can be used, bypassing the cloud service. This can result in significant time savings (15s vs 25s in one example) as well as less time between sending the request and the first visible change on the display. This is especially useful for the 4.2" model with buttons, as the time a user spends waiting after pressing a button can be significantly reduced.
+
+To enable direct rendering, create a file named signhubs.cfg in either the same directory as your app, the current directory, or /etc/signhubs.cfg. This file should have the following format:
+hub-serial-nbr  hub-ip  hub-apikey
+
+As an example:
+MCFEF5583A9DCA  192.168.0.50  8ab8125b-5d23-1b9a-e55e-a8b3d8c04614
+
+Once this is created, you can test it using examples/hubs.rb which should now list your hub as direct rendering capable. To enable this in your app, pass "render\_direct: true" when instantiating a new SyncSign::Service object.
+
+
 ## Examples
 
 Check out the examples/ folder for:
  * account\_info.rb - Show information about the account associated with the provided API key.
  * nodes.rb - List all nodes on the system and information about them.
+ * hubs.rb - List all hubs on the system and whether we have enough info to support direct rendering.
  * render.rb - Render a sample screen to the given node.
+ * symbols.rb - Shows how to use the Symbolbox to utilize display-resident symbols.
+ * partial\_update.rb - Perform a screen render, then update that render with extra information.
 
+## Full Documentation
+YARD docs included, also available on [RubyDoc.info](https://www.rubydoc.info/github/sarahemm/ruby-syncsign/master)

data/lib/syncsign/hub.rb

@@ -6,13 +6,18 @@ module SyncSign
     attr_reader :sn
     # @return [String] the friendly name of the hub.
     attr_reader :name
-    
+    # @return [String] the IP address or hostname of the hub.
+    attr_reader :addr
+    # @return [String] the API key of the hub.
+    attr_reader :apikey
+
     ##
     # Initialize a new hub object (normally only called from Service#hubs)
-    def initialize(sn: null, name: null, service: null)
+    def initialize(service: nil, sn: nil, name: nil)
       @sn = sn
       @name = name
       @service = service
+      load_hub_info
     end
     
     ##
@@ -20,6 +25,38 @@ module SyncSign
     def nodes
       SyncSign::Node::parse_collection(service: @service, nodeinfo: @service.api_call(path: "/devices/#{@sn}/nodes"))
     end
+
+
+    def direct_rendering_capable?
+      return @addr && @apikey
+    end
+
+    private
+
+    ##
+    # Load info about a hub from the config file (IP address and API key)
+    def load_hub_info
+      cfg_locations = [
+        "./signhubs.cfg",
+        "#{File::dirname($0)}/signhubs.cfg",
+        "/etc/signhubs.cfg"
+      ]
+      cfgfile = cfg_locations.find { |file| File.exist?(file) }
+      return unless cfgfile
+
+      File.open(cfgfile) do |f|
+        f.each_line do |line|
+          next if line[0] == "#"
+
+          hubinfo = line.split(/\s+/)
+          if(@sn == hubinfo[0]) then
+            @addr = hubinfo[1]
+            @apikey = hubinfo[2]
+            return true
+          end
+        end
+      end
+    end
   end
 end
 

data/lib/syncsign/node-display.rb

@@ -5,8 +5,10 @@ module SyncSign
     ##
     # Render a template to this display.
     # @param template [Template] Template to render to this display.
-    def render(template: nil)
-      @service.api_call(type: :post, path: "/nodes/#{@id}/renders", data: template.to_s)
+    # @param partial [Boolean] Specifies that this should be a partial update,
+    # leaving any information already on the screen in place.
+    def render(template: nil, partial: false)
+      @service.api_call(type: :post, path: "/nodes/#{@id}/renders", data: template.to_s(partial: partial), node: self, direct: @service.direct_rendering?)
     end
 
     ##

data/lib/syncsign/node.rb

@@ -16,7 +16,7 @@ module SyncSign
 
     ##
     # Initialize a new Node object (normally only called from Hub#nodes or Service#nodes).
-    def initialize(service: nil, id: nil, name: nil, online: nil, battery: nil, signal: nil, model: nil)
+    def initialize(service: nil, id: nil, name: nil, online: nil, battery: nil, signal: nil, model: nil, hubid: nil)
       @service = service
       @id = id
       @name = name
@@ -24,6 +24,7 @@ module SyncSign
       @battery = battery
       @signal = signal
       @model = model
+      @hubid = hubid
     end
 
     ##
@@ -32,6 +33,12 @@ module SyncSign
       @online
     end
 
+    ##
+    # Return the hub that this node is associated with
+    def hub
+      Hub.new(service: @service, sn: @hubid)
+    end
+
     ##
     # Parse a JSON description of a single node into a +Node+ object.
     # Normally only called from Hub#nodes or Service#nodes.
@@ -50,7 +57,8 @@ module SyncSign
         online: nodeinfo['onlined'],
         battery: nodeinfo['batteryLevel'],
         signal: nodeinfo['signalLevel'],
-        model: nodeinfo['model']
+        model: nodeinfo['model'],
+        hubid: nodeinfo['thingName']
       )
     end
     

data/lib/syncsign/service.rb

@@ -16,8 +16,11 @@ module SyncSign
     ##
     # Set up a new connection to the SyncSign cloud service.
     # @param apikey [String] the API key provided through the SyncSign portal.
-    def initialize(apikey: null)
+    # @param render_direct [Boolean] try to send renders directly to the hub,
+    # bypassing the cloud service.
+    def initialize(apikey: nil, render_direct: false)
       @apikey = apikey
+      @directrender = render_direct
       @baseurl = "https://api.sync-sign.com/v2/key/#{apikey}"
     end
 
@@ -57,16 +60,28 @@ module SyncSign
       Node::parse(service: self, nodeinfo: api_call(path: "/nodes/#{id}"))
     end
 
+    ##
+    # Query whether we are rendering direct to the hub or via the cloud.
+    def direct_rendering?
+      @directrender
+    end
+
     ##
     # Make a call to the SyncSign cloud service.
     # @param type [Symbol] The HTTP method to use, either :get or :put.
     # @param path [String] The path to make the API call to, minus the base path.
     # @param data [String] The POST data to send with the API call.
+    # @param direct [Boolean] Whether to try to send the call directly to the hub,
+    # bypassing the cloud service.
+    # @param node [Node] The SyncSign node that this request is associated with.
+    # Optional unless using direct rendering, in which case it is required.
     # @api private
-    def api_call(type: :get, path: "", data: "")
-      apiurl = URI.parse("#{@baseurl}#{path}")
+    def api_call(type: :get, path: "", data: "", direct: false, node: nil)
+      baseurl = @baseurl
+      baseurl = "http://#{node.hub.addr}/key/#{node.hub.apikey}" if direct and node.hub.direct_rendering_capable?
+      apiurl = URI.parse("#{baseurl}#{path}")
       http_obj = Net::HTTP.new(apiurl.host, apiurl.port)
-      http_obj.use_ssl = true
+      http_obj.use_ssl = baseurl.include?("https")
       response = nil
       http_obj.start() do |http|
         req = nil

data/lib/syncsign/template.rb

@@ -14,9 +14,12 @@ module SyncSign
     # @param items [Array] List of Widgets to add to the template.
     # @param pollrate [Integer] How often (in ms) the node should poll the hub
     #   for new information.
-    def initialize(bgcolour: :white, items: [], pollrate: 10000)
+    # @param enable_buttons [Boolean] Whether to enable the button labels at
+    #   the bottom of the screen.
+    def initialize(bgcolour: :white, items: [], pollrate: 10000, enable_buttons: false)
       @bgcolour = bgcolour
       @pollrate = pollrate
+      @enable_buttons = enable_buttons
       
       @items = []
       items.each do |item|
@@ -34,17 +37,24 @@ module SyncSign
     
     ##
     # Output this template as JSON in the format that the SyncSign service understands.
-    def to_s
-      background = {bgColor: @bgcolour.to_s.upcase}
+    # @param partial [Boolean] Whether to omit the background, which leaves
+    # any information already on-screen in place.
+    def to_s(partial: false)
+      background = {
+        bgColor: @bgcolour.to_s.upcase,
+        enableButtonZone: @enable_buttons
+      }
       items = @items.collect { |item| item.to_a }
       options = {'pollRate': @pollrate}
-      {
+      tmpl = {
         layout: {
           background: background,
           items: items,
           options: options
         }
-      }.to_json
+      }
+      tmpl[:layout].delete(:background) if partial
+      tmpl.to_json
     end
   end
 end

data/lib/syncsign/version.rb

@@ -1,4 +1,4 @@
 module SyncSign
   # The version number of the SyncSign module.
-  VERSION = '0.2.0'
+  VERSION = '0.4.2'
 end

data/lib/syncsign/widget-core.rb

@@ -0,0 +1,76 @@
+module SyncSign
+  ##
+  # Raised when UI elements are not properly aligned.
+  # Several UI elements must be aligned to a multiple of 8 or corruption will
+  # occur on the display.
+  class AlignmentException < StandardError
+  end
+
+  ##
+  # Widgets are UI elements that are placed onto a +Template+ for rendering.
+  class Widget
+    ##
+    # An item that contains only x/y coordinates. This can't be used on its own, only its
+    # superclasses can be added to templates.
+    class Item
+      # @return [Integer] horizontal position of the item.
+      attr_accessor :x
+      # @return [Integer] vertical position of the item.
+      attr_accessor :y
+      
+      ##
+      # Initialize a new Item widget.
+      # @param x [Integer] The horizontal position of the item.
+      # @param y [Integer] The vertical position of the item.
+      def initialize(x: nil, y: nil)
+        @x = x
+        @y = y
+      end
+    end
+
+    ##
+    # A box that contains x/y coordinates, width and height, and colour information.
+    # This can't be used on its own, only its superclasses can be added to templates.
+    # You may be looking for +Rectangle+ if you want to draw rectangles.
+    class Box < Item
+      # @return [Integer] the width of the box.
+      attr_accessor :width
+      # @return [Integer] the height of the box.
+      attr_accessor :height
+      # @return [Symbol] the stroke or foreground colour of the box.
+      attr_accessor :colour
+      # @return [Symbol] the background colour of the box.
+      attr_accessor :bgcolour
+
+      def initialize(x: nil, y: nil, width: nil, height: nil, colour: :black, bgcolour: :white)
+        Widget::check_colours [colour, bgcolour]
+        @colour = colour
+        @bgcolour = bgcolour
+        @width = width
+        @height = height
+        super(x: x, y: y)
+      end
+    end
+
+    ##
+    # Check a set of colours to make sure they're all valid.
+    # Will raise ArgumentError if any elements are not valid colours.
+    # @param colours [Array] An array of symbols to check.
+    def self.check_colours(colours)
+      colours.each do |colour|
+        next if [:white, :black, :red].include? colour
+        raise ArgumentError, "Colour must be :white, :black, or :red."
+      end
+    end
+    
+    # Check a set of patterns to make sure they're all valid.
+    # Will raise ArgumentError if any elements are not valid patterns.
+    # @param patterns [Array] An array of symbols to check.
+    def self.check_patterns(patterns)
+      patterns.each do |pattern|
+        next if [:solid, :interleave, :dash_tiny, :dash_medium, :dash_wide, :none].include? pattern
+        raise ArgumentError, "Pattern must be :solid, :interleave, :dash_tiny, :dash_medium, :dash_wide, or :none."
+      end
+    end
+  end
+end

data/lib/syncsign/widgets/buttonlabels.rb

@@ -0,0 +1,46 @@
+module SyncSign
+  class Widget
+    ##
+    # A widget that draws button labels for the 4.2" display.
+    class ButtonLabels
+      # @return [Array] Up to 4 strings of 17 characters each, to label the buttons with.
+      attr_accessor :labels
+      # @return [Array] Up to 4 boolean values showing whether each button should be reverse colours.
+      attr_accessor :reversed
+      
+      ##
+      # Initialize a new Button Labels widget.
+      # @param labels [Array] Up to 4 strings of 17 characters each, to label the buttons with.
+      # @param reversed [Array] Up to 4 boolean values showing whether each button should be reverse colours (white on black). Default is black on white.
+      def initialize(labels: [], reversed: [])
+        # TODO: validate <= 17 characters in each label
+        @labels = labels
+        @reversed = reversed
+      end
+
+      ##
+      # Convert the widget into an array for sending to the SyncSign service.
+      def to_a
+        label_arr = []
+        (0..3).each do |idx|
+          label_arr[idx] = {
+            :title => @labels[idx] || "",
+            :style => @reversed[idx] || 'DISABLED'
+          }
+        end
+
+        {
+          'type': 'BOTTOM_CUSTOM_BUTTONS',
+          'data': {
+            'list': label_arr
+          }
+        }
+      end
+
+      def ==(other)
+        @labels == other.labels &&
+        @reversed == other.reversed
+      end
+    end
+  end
+end

data/lib/syncsign/widgets/circle.rb

@@ -0,0 +1,63 @@
+module SyncSign
+  class Widget
+    ##
+    # A widget that draws a circle.
+    class Circle < Item
+      attr_accessor :radius, :bgcolour, :colour, :fillpattern, :strokepattern
+
+      ##
+      # Initialize a new circle widget.
+      # @param x [Integer] horizontal position of the centre of the circle.
+      # @param y [Integer] vertical position of the centre of the circle
+      # @param radius [Integer] The radius of the circle in pixels.
+      # @param colour [Symbol] The stroke colour used for the circle
+      #   (either black, white, or red).
+      # @param bgcolour [Symbol] The fill colour used for the circle
+      #   (either black, white, or red).
+      # @param fillpattern [Symbol] The fill pattern to use when filling the circle.
+      # @param strokepattern [Symbol] The stroke pattern to use when drawing the circle.
+      # @param pen_width [Integer] The thickness in pixels of the stroke.
+      def initialize(x: nil, y: nil, radius: nil, bgcolour: :white, colour: :black, fillpattern: :none, strokepattern: :solid, pen_width: 1)
+        Widget::check_colours [colour, bgcolour]
+        Widget::check_patterns [fillpattern, strokepattern]
+        @radius = radius
+        @colour = colour
+        @bgcolour = bgcolour
+        @fillpattern = fillpattern
+        @strokepattern = strokepattern
+        @pen_width = pen_width
+        super(x: x, y:y)
+      end
+      
+      ##
+      # Convert the widget into an array for sending to the SyncSign service.
+      def to_a
+        {
+          'type': 'CIRCLE',
+          'data': {
+            'center': {x: @x, y: @y},
+            'radius': @radius,
+            'fillColor': @bgcolour.to_s.upcase,
+            'fillPattern': @fillpattern.to_s.upcase,
+            'strokeColor': @colour.to_s.upcase,
+            'strokePattern': @strokepattern.to_s.upcase,
+            'strokeThickness': @pen_width
+          }
+        }
+      end
+
+      def ==(other)
+        @x == other.x                         &&
+        @y == other.x                         &&
+        @width == other.width                 &&
+        @height == other.height               &&
+        @radius == other.radius               &&
+        @bgcolour == other.bgcolour           &&
+        @colour == other.colour               &&
+        @fillpattern == other.fillpattern     &&
+        @strokepattern == other.strokepattern &&
+        @pen_width == other.pen_width
+      end
+    end
+  end
+end

data/lib/syncsign/widgets/line.rb

@@ -0,0 +1,56 @@
+module SyncSign
+  class Widget
+    ##
+    # A widget that draws a line.
+    class Line
+      attr_accessor :x0, :y0, :x1, :y1, :bgcolour, :colour, :pattern
+
+      ##
+      # Initialize a new line widget.
+      # @param x0 [Integer] horizontal position of the starting point of the line.
+      # @param y0 [Integer] vertical position of the starting point of the line.
+      # @param x1 [Integer] horizontal position of the ending point of the line.
+      # @param y1 [Integer] vertical position of the ending point of the line.
+      # @param colour [Symbol] The stroke colour used for the rectangle
+      #   (either black, white, or red).
+      # @param bgcolour [Symbol] The fill colour used for the rectangle
+      #   (either black, white, or red).
+      # @param pattern [Symbol] The linestyle to use when drawing the line, one of solid, interleave, dash_tiny, dash_mid, or dash_wide.
+      def initialize(x0: nil, y0: nil, x1: nil, y1: nil, bgcolour: :white, colour: :black, pattern: :solid)
+        Widget::check_colours [colour, bgcolour]
+        Widget::check_patterns [pattern]
+        @x0 = x0
+        @y0 = y0
+        @x1 = x1
+        @y1 = y1
+        @colour = colour
+        @bgcolour = bgcolour
+        @pattern = pattern
+      end
+      
+      ##
+      # Convert the widget into an array for sending to the SyncSign service.
+      def to_a
+        {
+          'type': 'LINE',
+          'data': {
+            'block': {x0: @x0, y0: @y0, x1: @x1, y1: @y1},
+            'backgroundColor': @bgcolour.to_s.upcase,
+            'lineColor': @colour.to_s.upcase,
+            'linePattern': @pattern.to_s.upcase
+          }
+        }
+      end
+
+      def ==(other)
+        @x0 == other.x0             &&
+        @y0 == other.y0             &&
+        @x1 == other.x1             &&
+        @y1 == other.y1             &&
+        @bgcolour == other.bgcolour &&
+        @colour == other.colour     &&
+        @pattern == other.pattern
+      end
+    end
+  end
+end

data/lib/syncsign/widgets/qrcode.rb

@@ -0,0 +1,62 @@
+module SyncSign
+  class Widget
+    # A widget that draws a QR code.
+    class QRCode < Item
+      # @return [Integer] scale of the QR code (how many pixels to use to
+      #   represent each base pixel).
+      attr_accessor :scale
+      # @return [Integer] the version (which is actually size, in QR-speak)
+      #   of this QR code.
+      attr_accessor :version
+      # @return [Symbol] the level of error checking code for this QR code,
+      #   either :low, :medium, :quartile, or :high.
+      attr_accessor :ecclevel
+      # @return [String] the text to encode in this QR code.
+      attr_accessor :text
+      
+      ##
+      # Initialize a new QR code widget.
+      # @param x [Integer] horizontal position of the left side of the QR code.
+      # @param y [Integer] vertical position of the top of the QR code.
+      # @param scale [Integer] scale of the QR code (how many pixels to use to
+      #   represent each base pixel).
+      # @param version [Integer] the version (which is actually size, in QR-speak)
+      #   of this QR code. 
+      # @param ecclevel [Symbol] the level of error checking code for this QR code,
+      #   either :low, :medium, :quartile, or :high. 
+      # @param text [String] the text to encode in this QR code.
+      def initialize(x: nil, y: nil, scale: 4, version: 2, ecclevel: :medium, text: nil)
+        @scale = scale
+        @version = version
+        @ecclevel = ecclevel
+        @text = text
+
+        super(x: x, y: y)
+      end
+
+      ##
+      # Convert the widget into an array for sending to the SyncSign service.
+      def to_a
+        {
+          'type': 'QRCODE',
+          'data': {
+            'scale': @scale,
+            'eccLevel': @ecclevel.to_s.upcase,
+            'version': @version,
+            'position': {x: @x, y: @y},
+            'text': @text
+          }
+        }
+      end
+
+      def ==(other)
+        @x == other.x               &&
+        @y == other.y               &&
+        @scale == other.scale       &&
+        @version == other.version   &&
+        @ecclevel == other.ecclevel &&
+        @text == other.text
+      end
+    end
+  end
+end

data/lib/syncsign/widgets/rectangle.rb

@@ -0,0 +1,57 @@
+module SyncSign
+  class Widget
+    ##
+    # A widget that draws a rectangle.
+    class Rectangle < Box
+      attr_accessor :pen_width
+      
+      ##
+      # Initialize a new rectangle widget.
+      # @param x [Integer] horizontal position of the left side of the rectangle.
+      # @param y [Integer] vertical position of the top of the rectangle.
+      # @param width [Integer] how wide the rectangle should be.
+      # @param height [Integer] how tall the rectangle should be.
+      # @param colour [Symbol] The stroke colour used for the rectangle
+      #   (either black, white, or red).
+      # @param bgcolour [Symbol] The fill colour used for the rectangle
+      #   (either black, white, or red).
+      # @param pen_width [Integer] The width in pixels of the stroke.
+      def initialize(x: nil, y: nil, width: nil, height: nil, colour: :black, bgcolour: :white, pen_width: 1, fillpattern: :none, strokepattern: :solid)
+        Widget::check_patterns [fillpattern, strokepattern]
+        raise(AlignmentException, "Rect: x and width must both be a multiple of 8") if x % 8 != 0 or width % 8 != 0
+        @pen_width = pen_width
+        @fillpattern = fillpattern
+        @strokepattern = strokepattern
+        super(x: x, y: y, width: width, height: height, colour: colour, bgcolour: bgcolour)
+      end
+      
+      ##
+      # Convert the widget into an array for sending to the SyncSign service.
+      def to_a
+        {
+          'type': 'RECTANGLE',
+          'data': {
+            'block': {x: @x, y: @y, w: @width, h: @height},
+            'fillColor': @bgcolour.to_s.upcase,
+            'fillPattern': @fillpattern.to_s.upcase,
+            'strokeColor': @colour.to_s.upcase,
+            'strokePattern': @strokepattern.to_s.upcase,
+            'strokeThickness': @pen_width
+          }
+        }
+      end
+
+      def ==(other)
+        @x == other.x                           &&
+        @y == other.y                           &&
+        @width == other.width                   &&
+        @height == other.height                 &&
+        @colour == other.colour                 &&
+        @bgcolour == other.bgcolour             &&
+        @pen_width == other.pen_width           &&
+        @fillpattern == other.fillpattern       &&
+        @strokepattern == other.strokepattern
+      end
+    end
+  end
+end