https://github.com/cbetta/doxie
Ruby Doxie API library for getting scans off your Doxie scanner 🖨
https://github.com/cbetta/doxie
doxie doxie-api libraries scanner sdk
Last synced: about 1 year ago
JSON representation
Ruby Doxie API library for getting scans off your Doxie scanner 🖨
- Host: GitHub
- URL: https://github.com/cbetta/doxie
- Owner: cbetta
- License: mit
- Created: 2016-05-29T20:29:50.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2022-10-05T22:46:51.000Z (over 3 years ago)
- Last Synced: 2024-04-25T14:43:56.496Z (about 2 years ago)
- Topics: doxie, doxie-api, libraries, scanner, sdk
- Language: Ruby
- Homepage: https://getdoxie.com/
- Size: 236 KB
- Stars: 5
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Ruby API library for Doxie Go Wifi
[](https://badge.fury.io/rb/doxie) [](https://travis-ci.com/cbetta/doxie)
A client library for the API available on WiFi-enabled [Doxie scanners](http://getdoxie.com). The specification of the API is available in their [developer documentation](/docs).
## 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.
```rb
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`](https://github.com/cbetta/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.
```rb
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.
```rb
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`](https://github.com/cbetta/doxie-scanner) gem to automatically connect to any scanner found.
```rb
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.
```rb
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.
```rb
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.
```rb
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.
```rb
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.
```rb
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.
```rb
client.scan "/DOXIE/JPEG/IMG_0001.JPG"
=> "...?]?1:Xt?????'A??}:?13???z*???}?rT???????z!ESj?/?..."
```
The other is to pass in a filename:
```rb
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.
```rb
client.thumbnail "/DOXIE/JPEG/IMG_0001.JPG"
=> "...?]?1:Xt?????'A??}:?13???z*???}?rT???????z!ESj?/?..."
```
The other is to pass in a filename:
```rb
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.
```rb
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`)
### `POST /scans/delete.json`
Deletes multiple scans in a single operation. This is much faster than deleting
each scan individually.
```rb
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`)
## 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](https://github.com/timcraft) for the excellent [Nexmo Ruby library](https://github.com/Nexmo/nexmo-ruby) which helped me remember how to nicely wrap the Doxie API.
This library is released under the [MIT License](LICENSE).