papirus 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a76933b098f5b78df7b2d885b938f171fa79896d
-  data.tar.gz: e8d561a393c6380ef13b0c674a4e62171dbd30de
+  metadata.gz: 5a26e1edf6b65c615e866725ea32e8c76b376a7e
+  data.tar.gz: 799cc512691f78a1400a588d0f1c19ed3c6a418a
 SHA512:
-  metadata.gz: 97fcf810d33adf0868454ffd407a71ee2038032cec814a3bdc771302db9b9f1535d928c5c59b0c66456014495c0bb3e075e8e657d2c3c001b88d54ba630d4d22
-  data.tar.gz: d561835c1dfa3dfda5f73918bcccc5ef9cc210498cc137dc84ff1a179bb59b9ee37b352af94e9b5e9afa7f2de2b4a13e6d8b40485a1970a53bd0ab5ac6621230
+  metadata.gz: a821ef2457c0ccfdf3ccb826e99b9920b97401032dc61ac6a48edc0a7c38b24efa49e550f9150f3430d3c3b2029515fba120c8462277b020d10cf2e85234767a
+  data.tar.gz: 8c7da2f32417ca1953fe23209bae94d4491467d82c6682b47f5a6424cfdd2c728d53b6cf849aeec9a3bb3e77317b350b096023a1e2a47d45cd3ed229cd8e2fc2

data/README.md

@@ -24,59 +24,32 @@ You can find more detailed instructions and updates at the [gratis](https://gith
 $ gem install papirus
 ```
 
-## usage
-
-```ruby
-require 'papirus'
-
-# first we get ourself a display
-display = PaPiRus::Display.new()
-```
-
-## there are multiple screen commands ['F', 'P', 'U', 'C']
-
-The `image.to_bit_stream` will be explained for both RMagic and ChunkyPNG below
-
-Full update (with screen cleaning):
-
-`display.show(image.to_bit_stream(display.width, display.height))`
-
-Fast update:
-
-`display.show(image.to_bit_stream(display.width, display.height)), 'F')`
-
-Partial update:
-
-`display.show(image.to_bit_stream(display.width, display.height), 'P')`
-
-# Playing with RMagic
+# Using with RMagic
 
 First install rmagick
 
 ```bash
-$ # install native Image Magick library
+$ # Install native Image Magick library
 $ (OSX) brew install imagemagick@6 && brew link imagemagick@6 --force
 $ (debian/ubuntu) sudo apt-get install imagemagick
 $ (Windows) no idea (did not use windows for 20 years, and would like to add some more)
-$ # install the gem that talks to the native Image Magick library
+$ # Install the gem that talks to the native Image Magick library
 $ gem install rmagick
 ```
 
-Then, start an irb session to play around
-```ruby
-require 'papirus'
-require 'papirus/rmagick'
+## Using an irb session to play around:
 
+```
+$ bundle exec irb -r lib/papirus -r ./lib/papirus/rmagick
 display = PaPiRus::Display.new()
 image = Magick::Image::read('/path/to/img/file.[png|jpg|etc]').first
 display.show(image.to_bit_stream(display.width, display.height))
 ```
 
-# Playing with Chunky_PNG
-
-First install chunky_png
+# Using with ChunkyPNG
 
 ```bash
+# install on
 $ (OSX) brew install chunky_png
 $ (debian/ubuntu) sudo apt-get install chunky_png
 $ (Windows) no idea (did not use windows for 20 years, and would like to add some more)
@@ -86,9 +59,7 @@ $ gem install chunky_png
 ## Load an image from a png file
 
 ```ruby
-irb
-require 'papirus'
-require 'papirus/chunky'
+$ bundle exec irb -r lib/papirus -r ./lib/papirus/chunky
 display = PaPiRus::Display.new()
 image = ChunkyPNG::Image.from_file('out.png')
 display.show(image.to_bit_stream(display.width, display.height))
@@ -98,15 +69,16 @@ The only problem here is the aspect ration of the image is not ok anymore. is a
 But for now you could also use Image magick's convert tool to rescale  the image and place it in the middle
 
 First, let's use Image Magick's `convert` tool to convert any image into an scaled, centered png
+
 ```bash
 convert in.jpg -resize '264x176' -gravity center -extent '264x176' out.png
 ```
 
 now, load it like explaned above and the image should be in the right aspect ration
 
-## Playing with drawing circles
+## Drawing circles with ChunkyPNG
 
-```ruby
+```
 irb
 require 'papirus'
 require 'papirus/chunky' # add's to_bit_stream function to chucky
@@ -117,9 +89,9 @@ image = ChunkyPNG::Image.new(display.width, display.height, ChunkyPNG::Color::WH
 image.circle(display.width/2, display.height/2, display.height/2-2)
 ```
 
-have a look at [chunky_png](https://github.com/wvanbergen/chunky_png/wiki) for more examples
+have a look at [chunkypng](https://github.com/wvanbergen/chunky_png/wiki) for more examples
 
-```ruby
+```
 #and last we dump the image as bitsteam to the display
 display.show(image.to_bit_stream)
 
@@ -137,18 +109,43 @@ display.clear
 end
 ```
 
+## there are multiple screen commands ['F', 'P', 'U', 'C']
+
+Full update (with screen cleaning):
+
+```
+display.show(image.to_bit_stream(display.width, display.height))
+```
+
+Fast update:
+
+```
+display.show(image.to_bit_stream(display.width, display.height)), 'F')
+```
+
+Partial update:
+
+```
+display.show(image.to_bit_stream(display.width, display.height), 'P')
+```
+
 ## Testing without a PaPiRus display
 
 If you want to test the gem, but don't have your PaPiRus available, you can do the following
 
-* clone this repo
+ clone this repo
 * start irb
-* require 'papirus'
-The gem will create the epd_path test folder and will add all params for the 2.0 panel
-* display = PaPiRus::Display.new(epd_path: '/tmp/epd')
-When you want to add the 2.7 display panel, you would do 
-* display = PaPiRus::Display.new(epd_path: '/tmp/epd', width: 264, height: 176, panel: 'EPD 2.7')
+
+```
+$ bundle exec irb -r ./lib/papirus
+# The gem will create the epd_path test folder (the folder needs to be somwhere in /tmp/) and will set it by default to the 2.0 panel
+display = PaPiRus::Display.new(options:{epd_path: '/tmp/epd'})
+# When you want to add the 2.7 display panel, you would do
+display = PaPiRus::Display.new(options:{epd_path: '/tmp/epd', width: 264, height: 176, panel: 'EPD 2.7'})
+```
+
 Now play with the examples above
+
 * when you run `display.show` the **fake** display /tmp/epd/LE/display is filled with your image
 * now you can use a bin editor like xxd to have a look at the result: `xxd -b /tmp/epd/LE/display`
 * or, use `image.inspect_bitstream(display.width, display.height)` to dump the image as 1's and 0's to the terminal
@@ -157,9 +154,11 @@ Now play with the examples above
 ## handy convert command
 
 This Image Magick convert command creates a 1-bit 2-color png
+
 ```bash
 convert in.jpg -resize '264x176' -gravity center -extent '264x176' -colorspace gray  -colors 2 -type bilevel out.png
 ```
+
 Where
 * the -resize scales the image to fit the display
 * The -gravity and -extent combination (order is important!) makes sure the image stays at the size of the display and in the centre
@@ -177,3 +176,24 @@ Where
 ## Other resources
 
 * [pi supply python driver](https://github.com/PiSupply/PaPiRus)
+
+## Development
+
+* Install bundler with ```gem install bundler```
+* Run ```bundle install``` to get all the gems
+* Create the documentation with: ```bundle exec yard```
+* Run the tests with: ```bundle exec rake yard:doctest```
+
+## Contributing to papirus
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add unit tests for it. This is important so I don't break it in a future version unintentionally.
+* Create a PR
+
+## Copyright
+
+Copyright (c) 2017 Mischa Molhoek. See LICENSE.txt for further details.

data/lib/papirus.rb

@@ -1,72 +1,131 @@
+# The PaPiRus::Display can be use to send image data to the
+# epd fuse driver
+#
+# Example usage
+#    require 'papirus'
+#    require 'papirus/rmagick'
+#    display = PaPiRus::Display.new()
+#    image = Magick::Image::read('/path/to/img/file.[png|jpg|etc]').first
+#    display.show(image.to_bit_stream(display.width, display.height))
 module PaPiRus
-    # The {PaPiRus::Display} can be use to send image data to the
-    # epd fuse driver
+    # Default epd driver path
+    EPDPATH = '/dev/epd'
+
     class Display
         attr_reader :epd_path, :width, :height, :panel, :cog, :film, :auto, :allowed_commands, :display_path
         attr_accessor :rotation, :inverse, :image
         # The possible commands to send to the display with {PaPiRus::Display.command}
-        # can be eitheri
-        # 'U' for update
-        # 'F' for fast update
-        # 'P' for partial update
-        # or 'C' for clearing the screen
+        # can be either
+        #  'U' for update
+        #  'F' for fast update
+        #  'P' for partial update
+        #  or 'C' for clearing the display
+        # @return [Array<String>] All allowed command strings
         attr_reader :allowed_commands
-
-        def initialize(epd_path: '/dev/epd', width: 200, height: 96, panel: 'EPD 2.0', cog: 2, film: 231, auto: false, inverse: false, rotation: 0)
-            if epd_path != '/dev/epd'
-                # assuming we use a test dir and it is not created yet
-                require 'fileutils'
-                raise 'epd test path should be located somewhere in /tmp/' unless epd_path =~ /\/tmp\/\w+/
-                if File.exists?(epd_path)
-                    #remove old test dir as it may be a different screen size/type
-                    FileUtils.rm_f(epd_path)
-                end
-                FileUtils.mkdir_p(File.join([epd_path, 'LE']))
-                %w{command LE/display, LE/display_inverse}.each do |file|
-                    FileUtils.touch File.join([epd_path, file])
-                end
-                File.open(File.join([epd_path, 'panel']), 'w+') do |file|
-                    file.write %{#{panel} #{width}x#{height} COG #{cog} FILM #{film}\n}
-                end
-            end
-            #transver all vars to attr's
-            method(__method__).parameters.each do |type, k|
-                next unless type == :key
-                v = eval(k.to_s)
-                instance_variable_set("@#{k}", v) unless v.nil?
-            end
-            @allowed_commands = ['F', 'P', 'U', 'C']
-            get_display_info_from_edp
+        # By default, no parameters need to be passed to initialize. It will read all display settings
+        # from the panel info file that is created by the fuse driver. However, if you want to test
+        # without the display being available, you can pass a fake epd_path set to a folder in /tmp
+        # in that case initialize will use all other params to create a fake fuse structure
+        #  PaPiRus display sizes:
+        #  1.44"     128 x 96
+        #  1.9"      144 x 128
+        #  2.0"      200 x 96
+        #  2.6"      232 x 128
+        #  2.7"      264 x 176
+        # All the examples used in the documentation are also used to unit testing the code with
+        # yard:doctest[https://github.com/p0deje/yard-doctest],
+        # so we have duomentation and testing in one go, great!
+        # * the display that is used for the examples is a 8x3 mini display for the sake of simplicity.
+        # * imagewithline is a test helper that create an image of 8x3 pixels
+        # * testdisplaylookslike is a test helper that shows the bit content of the display
+        # * lastcommand is a test helper that will show the last command send to the display
+        # @example Initializing the real display
+        #   display = PaPiRus::Display.new()
+        # @example Initializing the display for testing the 2.7 display
+        #   display = PaPiRus::Display.new(options:{epd_path: '/tmp/epd', width: 264, height: 176, panel: 'EPD 2.7'})
+        # @param [Hash] options The options setup options when using a fake display file structure for testing.
+        # @option options [String] :epd_path ('/tmp/epd') The path to the fake display fuse folder
+        # @option options [Integer] :width (200) The width of the fake display (defaults to the 2.0 display size)
+        # @option options [Integer] :height (96) The height of the fake display
+        # @option options [String] :panel ('EPD 2.0') The panel type
+        # @option options [String] :cog (2)
+        # @option options [String] :film (231)
+        # @option options [Boolean] :auto (false)
+        # @option options [Boolean] :inverse (false)
+        # @option options [Integer] :rotation (0)
+        def initialize(options: {})
+            initializeOptions(options: options)
+            createFakeEpdFileStructure(epd_path: @epd_path) if @epd_path != EPDPATH
+            updateOptionsFromPanel
         end
 
-        def show(*args)
-            raise 'you need to at least provide raw imagedata' if args.length == 0
-            data = args[0]
-            updatemethod = args[1] || 'U'
+        # Show can be used to send raw image data to the display.
+        # @param data [raw image data file] The file containing the raw 1-bits 2 color image bitmap without any header/footer/imageinfo
+        # @param command ['U'|'F'|'P']
+        # @example Show simpel image
+        #  display.show(data: imagewithline)
+        #  testdisplaylookslike #=> '000000001111111100000000'
+        #  lastcommand #=> 'U'
+        # @see #initialize if you are wondering what display type is used for the tests and what imagewithline  and lastcommand is all about
+        def show(data:, command: 'U')
             File.open(File.join(@epd_path, "LE", "display#{@inverse ? '_inverse': ''}"), 'wb') do |io|
                 io.write data
             end
-            command(@allowed_commands.include?(updatemethod) ? updatemethod : 'U')
+            command(@allowed_commands.include?(command) ? command : 'U')
         end
 
+        # Send the fast update command to the display
+        # @example Fast Update example
+        #  display.fast_update
+        #  lastcommand #=> 'F'
         def fast_update()
             command('F')
         end
 
+        # Send the partial update command to the display
+        # @example Partial Update example
+        #  display.partial_update
+        #  lastcommand #=> 'P'
         def partial_update()
             command('P')
         end
 
+        # Send the full update command to the display
+        # @example Full Update example
+        #  display.update
+        #  lastcommand #=> 'U'
         def update()
             command('U')
         end
 
+        # Send the clear command to the display
+        # @example Clear the display
+        #  display.clear
+        #  lastcommand #=> 'C'
         def clear()
             command('C')
         end
 
-        # send's the display command to the driver
-        # @param c [string] command to execute, have a look at {}
+        # Send's the display command to the driver
+        # available commands are
+        #   * 'U' => update the display
+        #   * 'F' => fast update the display
+        #   * 'P' => Partial update the display
+        #   * 'C' => Clear the display
+        # @param c [String] command to execute
+        #
+        # @example Clear the display
+        #   display.command('C')
+        #   lastcommand #=> 'C'
+        # @example Update the display
+        #   display.command('U')
+        #   lastcommand #=> 'U'
+        # @example Fast update the display
+        #   display.command('F')
+        #   lastcommand #=> 'F'
+        # @example Partial update the display
+        #   display.command('P')
+        #   lastcommand #=> 'P'
         def command(c)
             raise "command #{c} does not exist" unless @allowed_commands.include?(c)
             File.open(File.join(@epd_path, "command"), "wb") do |io|
@@ -75,15 +134,49 @@ module PaPiRus
         end
 
     private
-        # Reads all panel info and updates the according attributes
-        def get_display_info_from_edp
+        # Creates a fake test structure of the display fuse driver
+        def createFakeEpdFileStructure(epd_path:)
+            # assuming we use a test dir and it is not created yet
+            # test dirs can only be subdir of /tmp/
+            raise 'epd test path should be located somewhere in /tmp/' unless epd_path =~ /\/tmp\/\w+/
+            require 'fileutils'
+            #remove old test dir as it may be a different display size/type
+            if File.exists?(epd_path)
+                FileUtils.rm_f(epd_path)
+            end
+            #create all folders and files
+            FileUtils.mkdir_p(File.join([epd_path, 'LE']))
+            %w{command LE/display, LE/display_inverse}.each do |file|
+                FileUtils.touch File.join([epd_path, file])
+            end
+            #create the panel info file
+            File.open(File.join([epd_path, 'panel']), 'w+') do |file|
+                file.write %{#{@panel} #{@width}x#{@height} COG #{@cog} FILM #{@film}\n}
+            end
+        end
+
+        # Reads all panel info from /dev/epd/panel and updates the according attributes
+        def initializeOptions(options:)
+            @allowed_commands = ['F', 'P', 'U', 'C']
+            @epd_path = options[:epd_path] || EPDPATH
+            @width = options[:width] || 200
+            @height = options[:height] || 96
+            @panel = options[:panel] || "EPD 2.0"
+            @cog = options[:cog] || 2
+            @film = options[:film] || 231
+            @auto = options[:auto] || false
+            @inverse = options[:inverse] || false
+            @rotation = options[:rotation] || 0
+        end
+
+        def updateOptionsFromPanel
             if File.exists?(File.join(@epd_path, 'panel'))
                 info = File.read(File.join(@epd_path, 'panel'))
                 @display_path = File.join([@epd_path, 'LE', 'display'])
                 if match = info.match(/^([A-Za-z]+\s+\d+\.\d+)\s+(\d+)x(\d+)\s+COG\s+(\d+)\s+FILM\s+(\d+)\s*$/)
                     @panel, @width, @height, @cog, @film = match.captures.each_with_index.map{|val, index| index > 0 ? val.to_i : val}
                 else
-                    STDERR.puts "did not recognize screen info: #{info}, is the epd driver properly installed? have a look at the README.md to see how to install the epaper driver"
+                    STDERR.puts "did not recognize display info: #{info}, is the epd driver properly installed? have a look at the README.md to see how to install the epaper driver"
                     exit 1
                 end
             else
@@ -91,6 +184,5 @@ module PaPiRus
                 exit 1
             end
         end
-
     end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papirus
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Mischa Molhoek
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-10-28 00:00:00.000000000 Z
+date: 2017-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shoulda
@@ -80,6 +80,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: pry-nav
+  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: yard-doctest
+  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'
 description: This gem can be used to talk to the PaPiRus e-paper display
 email: mischamolhoek@gmail.com
 executables: []
@@ -88,12 +130,10 @@ extra_rdoc_files:
 - LICENSE
 - LICENSE.txt
 - README.md
-- README.rdoc
 files:
 - LICENSE
 - LICENSE.txt
 - README.md
-- README.rdoc
 - lib/papirus.rb
 - lib/papirus/chunky.rb
 - lib/papirus/rmagick.rb

data/README.rdoc

@@ -1,18 +0,0 @@
-= papirus
-
-This gem can be used to communicate with the {PaPiRus}[https://github.com/PiSupply/PaPiRus] display.
-Checkout {GitHub}[http://github.com/mmolhoek/papirus] for examples and documentation
-
-== Contributing to papirus
-
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
-* Fork the project.
-* Start a feature/bugfix branch.
-* Commit and push until you are happy with your contribution.
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2017 Mischa Molhoek. See LICENSE.txt for further details.