resin-image-write v4.0.2
resin-image-write
The cross-platform way to stream an OS image to a device
Installation
Install resin-image-write
by running:
$ npm install --save resin-image-write
Documentation
imageWrite.write(device, stream, options) ⇒ EventEmitter
NOTICE: You might need to run this function as sudo/administrator to avoid permission issues.
The returned EventEmitter instance emits the following events:
progress
: A progress event that passes a state object of the form:
{
type: 'write' // possible values: 'write', 'check'.
percentage: 9.05,
transferred: 949624,
length: 10485760,
remaining: 9536136,
eta: 10,
runtime: 0,
delta: 295396,
speed: 949624
}
error
: An error event.done
: An event emitted with a boolean success value.
Enabling the check
option is useful to ensure the image was
successfully written to the device. This is checked by calculating and
comparing checksums from both the original image and the data written
to the device.
The transform
option is used to handle cases like decompression of
an image on the fly. The stream is piped through this transform stream
after the progress stream and before any writing and alignment.
This allows the progress to be accurately displayed even when the client doesn't know the final uncompressed size.
For example, to handle writing a compressed file, you pass the
compressed stream to .write()
, pass the compressed stream size,
and a transform stream to decompress the file.
Kind: static method of imageWrite
Summary: Write a readable stream to a device
Returns: EventEmitter - emitter
Access: public
Param | Type | Default | Description |
---|---|---|---|
device | String | device | |
stream | ReadStream | readable stream | |
options | Object | options | |
options.size | Number | input stream size | |
options.transform | TransformStream | transform stream | |
options.check | Boolean | false | enable write check |
Example
var myStream = fs.createReadStream('my/image');
var emitter = imageWrite.write('/dev/disk2', myStream, {
check: true,
size: fs.statSync('my/image').size
});
emitter.on('progress', function(state) {
console.log(state);
});
emitter.on('error', function(error) {
console.error(error);
});
emitter.on('done', function(success) {
if (success) {
console.log('Success!');
} else {
console.log('Failed!');
}
});
Support
If you're having any problem, please raise an issue on GitHub and the Resin.io team will be happy to help.
Tests
Run the test suite by doing:
$ npm test
Contribute
- Issue Tracker: github.com/resin-io-modules/resin-image-write/issues
- Source Code: github.com/resin-io-modules/resin-image-write
Before submitting a PR, please make sure that you include tests, and that jshint runs without any warning:
$ npm run lint
License
resin-image-write
is free software, and may be redistributed under the terms specified in the license.