Images

Images are used in various places throughout Homey, such as album art for speakers, camera devices and in Flows.

When an Image is registered, it needs a way of providing Homey with it's data. This can be either:

  • an URL, available from anywhere on the internet
  • a getStream method that fills a stream with the binary data
  • a local path to a static image which is shipped with the App.

Note: Images are limited to 5 MB.

Creating an image

Using an URL

URLs should be used when the image is available from anywhere on the internet.

const myImage = new Homey.Image();
myImage.setUrl('https://www.example.com/image.png'); // the URL must start with https://
myImage.register().catch(console.error);

Using a Stream

Streams should be used when downloading an image that cannot be supplied using Image.setUrl. Using image streams involves writing data directly into a Node.js stream. Using streams Requires homey version 2.2.0 or higher.

const fetch = require('node-fetch');

const myImage = new Homey.Image();
myImage.setStream(async (stream) => {
  const res = await fetch('http://192.168.1.100/image.png');
  if(!res.ok)
    throw new Error('Invalid Response');

  return res.body.pipe(stream);
});
myImage.register().catch(console.error);

Using a Path

Paths should be used when the image is locally available.

const myImage = new Homey.Image();
myImage.setPath('/userdata/image.png');
myImage.register().catch(console.error);

Using a Buffer [DEPRECATED]

Buffers should be used when downloading an image that cannot be access anywhere in the world.

const fetch = require('node-fetch');

const myImage = new Homey.Image('png');
myImage.setBuffer(async () => {
  const res = await fetch('http://192.168.1.100/image.png');
  if(!res.ok)
    throw new Error('Invalid Response');

  return res.buffer();
});
myImage.register().catch(console.error);

Updating the image

Call Image.update() when the image has been updated, and the front-end will download the image again.

When your image uses a Stream, the method provided in setStream will be called again.

At any time, you can switch between delivery type by calling Image#setPath, Image#setStream or Image#setURL.

Retrieving an image

It is also possible to consume an image in your app, for instance through use of Flow Tokens.

const Homey 		= require('homey');
const {PassThrough} = require('stream');
const fetch 		= require('node-fetch');
const FormData 	= require('form-data');

//uploads an image to imgur and returns a link
async function uploadImage(image) {
  const stream = await image.getStream();

  const form = new FormData();

  form.append('image', stream, {
    contentType: stream.contentType,
    filename: stream.filename,
    name: 'image',
  });

  form.append('description', `This image can also be (temporarily) viewed at: ${image.cloudUrl} and ${image.localUrl}`);

  const response = await fetch("https://api.imgur.com/3/image", {
    method: 'POST',
    //pipe through a passthrough stream, workarround for a node-fetch bug involving form-data streams without content length set.
    body: form.pipe(new PassThrough()), 
    headers: {
      ...form.getHeaders(),
      Authorization: 'Client-ID <YOUR_CLIENT_ID>'
    }
  });
  if(!response.ok)
    throw new Error(response.statusText);
  
  const {data} = await response.json();
  return data.link;
}