Project

doxie

0.0
Low commit activity in last 3 years
No release in over a year
Doxie API Wrapper for getting scans off your Doxie scanner
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

 Project Readme

Ruby API library for Doxie Go Wifi

Gem Version Build Status

A client library for the API available on WiFi-enabled Doxie scanners. The specification of the API is available in their developer documentation.

Scanners Supported

This library supports the following scanners:

  • Doxie Go Wifi (DX250)
  • Doxie Go SE (DX255)
  • Doxie Q (DX300)

Installation

Either install directly or via bundler.

gem 'doxie'
gem 'doxie-scanner' # optional if your Doxie is not on a fixed IP

Usage

Optional: Finding your Doxie's IP

This optional step requires the doxie-scanner gem. This gem has a bigger dependency than the doxie gem, which is why it has been intentionally separated into a seperate library.

require 'doxie/scanner'
Doxie::Scanner.ips
=> [
    [0] "192.168.1.2"
]

Client

The client accepts an ip address, a scanner model number (defaults to Doxie::GO) and an optional password. You can omit the password if your Doxie has non set.

require 'doxie'
client = Doxie::Client.new(
    ip: '192.168.1.2', 
    model: Doxie::Q, # of Doxie::GO, or Doxie::GO_SE
    password: 'test'
)

Alternatively, you can use the doxie-scanner gem to automatically connect to any scanner found.

require 'doxie'
require 'doxie/scanner'

client = Doxie::Client.new(
  Doxie::Scanner.devices.first
)

GET /hello.json

Returns status information for the scanner, firmware, network mode, and password configuration. Accessing this command does not require a password if one has been set. The values returned depend on whether the scanner is creating its own network or joining an existing network.

client.hello
=> {
           "model" => "DX250",
            "name" => "Doxie_062300",
    "firmwareWiFi" => "1.29",
     "hasPassword" => true,
             "MAC" => "00:11:11:11:11:00",
            "mode" => "Client",
         "network" => "YourWifi",
              "ip" => "192.168.1.2"
}
  • model: DX250 for the Doxie Go WiFi, DX255 for the Doxie Go SE, and DX300 for the Doxie Q.
  • name: The name of the scanner, which defaults to the form "Doxie_XXXXXX". The name of a scanner can be changed by using the Doxie desktop app.
  • firmwareWiFi: The Wi-Fi firmware version.
  • hasPassword: Indicates whether a password has been set to authenticate API access. Passwords can be set and removed by using the Doxie desktop app.
  • MAC: The MAC address of the scanner as shown on the scanner's bottom label.
  • mode: "AP" if the scanner is creating its own network or "Client" if the scanner is joining an existing network.
  • network: If the scanner is in "Client" mode, this is the name of the network it has joined.
  • ip: If the scanner is in "Client" mode, this is the IP of the scanner on the network it has joined.

GET /hello_extra.json

Returns additional status values. These values are accessed separately from those in /hello.json because there can be a delay of several seconds in loading them. Accessing this command does not require a password if one has been set.

client.hello_extra
=> {
                    "firmware" => "0.26",
    "connectedToExternalPower" => true
}
  • firmware: The scanner firmware version.
  • connectedToExternalPower: Indicates whether the scanner is connected to its AC adapter versus running on battery power. This value is not cached, so it immediately reflects any state changes.

This method is only available for the original Doxie Go WiFi model.

GET /restart.json

Restarts the scanner's Wi-Fi system. The scanner's status light blinks blue during the restart.

client.restart
=> true

GET /scans.json

Returns an array of all scans currently in the scanner’s memory. After scanning a document, the scan will available via the API several second later.

client.scans
=> [
    [0] {
            "name" => "/DOXIE/JPEG/IMG_0001.JPG",
            "size" => 900964,
        "modified" => "2010-05-01 00:02:38"
    }
]

Calling this function immediately after scanning something may return a blank result, even if there are other scans on the scanner, due to the scanner's memory being in use. Consider retrying if a successful HTTP status code is returned along with a blank body.

GET /scans/recent.json

Returns the path to the last scan if available. Monitoring this value for changes provides a simple way to detect new scans without having to fetch the entire list of scans.

client.recent_scans
=> {
    "path" => "/DOXIE/JPEG/IMG_0001.JPG"
}

GET /scans/DOXIE/JPEG/IMG_XXXX.JPG

There are 2 ways to get a scan off your Doxie. The first is to get the raw binary content and then do something with it yourself.

client.scan "/DOXIE/JPEG/IMG_0001.JPG"
=> "...?]?1:Xt?????'A??}:<??13???z*???}?rT???????z!ESj?/?..."

The other is to pass in a filename:

client.scan "/DOXIE/JPEG/IMG_0001.JPG", 'test.jpg'
=> true

GET /thumbnails/DOXIE/JPEG/IMG_XXXX.JPG

There are 2 ways to get a thumbnail off your Doxie. The first is to get the raw binary content and then do something with it yourself.

client.thumbnail "/DOXIE/JPEG/IMG_0001.JPG"
=> "...?]?1:Xt?????'A??}:<??13???z*???}?rT???????z!ESj?/?..."

The other is to pass in a filename:

client.thumbnail "/DOXIE/JPEG/IMG_0001.JPG", 'test.jpg'
=> true

Thumbnails are constrained to fit within 240x240 pixels. Thumbnails for new scans are not generated until after the scan has been made available in /scans.json and /scans/recent.json. This function will return 404 Not Found if the thumbnail has not yet been generated. Retrying after a delay is recommended to handle such cases.

DELETE /scans/DOXIE/JPEG/IMG_XXXX.JPG

Deletes the scan at the specified path.

client.delete_scan "/DOXIE/JPEG/IMG_0001.JPG"
=> true

Deleting takes several seconds because a lock on the internal storage must be obtained and released. Deleting may fail if the lock cannot be obtained (e.g., the scanner is busy), so consider retrying on failure conditions. When deleting multiple scans, use /scans/delete.json for best performance.

This will raise an error if the file is no longer present (Doxie::Client::Error<Net::HTTPForbidden>)

POST /scans/delete.json

Deletes multiple scans in a single operation. This is much faster than deleting each scan individually.

client.delete_scans ["/DOXIE/JPEG/IMG_0001.JPG", "/DOXIE/JPEG/IMG_0002.JPG"]
=> true

This will raise an error if the files are no longer present (Doxie::Client::Error<Net::HTTPForbidden>)

Contributing

  1. Fork the repo on GitHub
  2. Clone the project to your own machine
  3. Commit changes to your own branch
  4. Push your work back up to your fork
  5. Submit a Pull request so that we can review your changes

Development

  • bundle install to get dependencies
  • rake to run tests
  • rake console to run a local console with the library loaded

Credits and License

Thanks to @timcraft for the excellent Nexmo Ruby library which helped me remember how to nicely wrap the Doxie API.

This library is released under the MIT License.