Images

This feature depends on Homey v2.2.0 please make sure your app.json manifest has a compatibility of ">=2.2.0"

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);

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;
}

Deprecated

Using a Buffer

In Homey versions before v2.2.0 it was required to specify an image format of either 'png', 'jpg' or 'gif'. From version v2.2.0 onward this format was ignored and the setBuffer api was deprecated, it is therefore reccommended that apps that use images specify a compatibility in the app.json manifest of at least ">=2.2.0".

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);