syncsign 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e261ff9af0745d4e8e96f7ea246dd5318a9dae6abf59572ae41ad0090d0b91d3
-  data.tar.gz: d0964bfcc113b69e72d54c7a513d3ad1156dc2ce6488fc6d2bc29ba1f9814495
+  metadata.gz: ecfc03f1b6335088ff04e9bbe56a78fd1942569b30ffb07e6a5a0094d8451a3e
+  data.tar.gz: cdd719e880cc9117d0dde045956c4e299a8de5c3fb4952a9aff5305c6d1ff1ea
 SHA512:
-  metadata.gz: c9cb756b7b3e6220a23912168fcb098652c038cecb2e3f085af83b917ea74db74429bc13241787c6b4137c894b2ec402336351d9d69a282b538c24adaf79ca30
-  data.tar.gz: c8bbd89fd3d3127b36977059accc5fbf340eb4ce13bdc83c5069949c68280babeb794ce16280a4d989494611cf968838b051e721254ad293b46ac4df9bdfa377
+  metadata.gz: 6e1e58973658b2fcc66b8cf538b123d9554f32966022689bf316f23592acf17241762034fc7c7082063e9099663dd75f55a1beec14e808dbff340e0508840dfc
+  data.tar.gz: 6f5ec20b8eda95908fd34a2012f108b16f623b97dec137a31eff4fca41d87387279ca4196b9f83608e59812ce29ab61d045f363962aec2e76d0f547a3c4c3544

data/README.md

@@ -12,7 +12,6 @@ Ruby class/gem to access the [SyncSign](http://sync-sign.com) cloud service to d
  * 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
 
@@ -48,6 +47,8 @@ Check out the examples/ folder for:
  * 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.rb

@@ -6,4 +6,12 @@ require 'syncsign/hub.rb'
 require 'syncsign/node.rb'
 require 'syncsign/node-display.rb'
 require 'syncsign/template.rb'
-require 'syncsign/widgets.rb'
+require 'syncsign/widget-core.rb'
+require 'syncsign/widgets/symbolbox-symbols.rb'
+require 'syncsign/widgets/buttonlabels.rb'
+require 'syncsign/widgets/circle.rb'
+require 'syncsign/widgets/line.rb'
+require 'syncsign/widgets/qrcode.rb'
+require 'syncsign/widgets/rectangle.rb'
+require 'syncsign/widgets/symbolbox.rb'
+require 'syncsign/widgets/textbox.rb'

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, node: self, direct: @service.direct_rendering?)
+    # @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/template.rb

@@ -37,20 +37,24 @@ module SyncSign
     
     ##
     # Output this template as JSON in the format that the SyncSign service understands.
-    def to_s
+    # @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.3.0'
+  VERSION = '0.4.1'
 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,62 @@
+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},
+            '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