Images

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

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

• an URL, available from anywhere on the internet

• a binary stream through the getStream method

• a local path to a static image which is shipped with the App.

Note: Images are limited to 5 MB.

You can debug your images in the Developer Tools.

Creating an image

Using an URL

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

/app.js

const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myImage = await this.homey.images.createImage();
    // the URL must start with https://
    myImage.setUrl("https://www.example.com/image.png");
  }
}

module.exports = App;

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.

/app.js

const Homey = require('homey');
const fetch = require("node-fetch");

class App extends Homey.App {
  async onInit() {
    const myImage = await this.homey.images.createImage();

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

module.exports = App;

Using a Path

Paths should be used when the image is locally available.

/app.js

const Homey = require('homey');

class App extends Homey.App {
  async onInit() {
    const myImage = await this.homey.images.createImage();
    myImage.setPath("/userdata/image.png");
  }
}

module.exports = App;

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 Image#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 { 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;
}