INGY Lighting

Article explaining how to use MobiusFlow INGY service. It is recommended you read this article in its entirety before using the MobiusFlow INGY integration.

Overview

The MobiusFlow INGY integration implements the following features:

• Changing lighting level set points of group scenes

• Switching between lighting scenes of a given group

• Adding / removing devices from groups

• Acquisition of data from INGY devices

• Direct interfacing with INGY API and Datastream

This article explains how to use the INGY service to achieve all of the above.

Connecting to INGY Gateway

To interface with an INGY system, an INGY gateway must be present on the project site. These INGY gateways can be acquired directly from INGY.

MQTT

The INGY gateway host's and MQTT broker, and as such, MobiusFlow uses an MQTT connection to this broker to allow two-way communication between MobiusFlow and INGY.

INGY gateways create 3 MQTT users, each with different sets of permissions. MobiusFlow requires usage of the datastream and MQTT JSON server (API) users. These user credentials can be found in the Gateway MQTT server section of the INGY gateway configuration page.

Network Requirements

Ensure the INGY gateway is accessible by MobiusFlow over an on-site (or otherwise) network. As it is likely the local IP address of the INGY gateway will be directly referenced within MobiusFlow, it is recommended that this should be set up on the network with a static local IP address. This means the connection will not break due to DHCP reassignment.

INGY Service Settings / Requirements

Once the INGY service has been added, the following configuration window is shown:

The following fields must be populated to allow MobiusFlow the connect the INGY gateway.

Setting	Explanation
MQTT Broker	The IP location of the MQTT broker (IP address, DNS name, or otherwise). For MQTT over TLS include mqtts:// prefix, otherwise, inclusion of protocol is not required.
MQTT Port	Run by INGY on 1883 by default.
MQTT Username (Datastream)	Found on INGY gateway configuration page.
MQTT Password (Datastream)	Found on INGY gateway configuration page.
MQTT Username (JSON API)	Found on INGY gateway configuration page.
MQTT Password (JSON API)	Found on INGY gateway configuration page.
INGY Firmware Version	85, 94, etc. To use mixed firmware versions, use multiple INGY services each with different firmware versions.

Checking connection

The INGY service will attempt to connect via MQTT to the INGY gateway when the service is started. As such, to test the connection, start the service and observe the service status:

Service status showing successful MQTT connection

Lighting Control

Lighting control is exclusively performed by commanding lighting groups to change to different scenes.

For every INGY lighting group, add an ingy_group (PID 028A) MobiusFlow object to represent the group within MobiusFlow. The group number of the INGY group can be set in the object settings.

Note that: If INGY groups have been pre-configured in the using the INGY App, ensure the group number matches that of group number displayed in the INGY App. See full section here.

New INGY group object with a group number 7001486

Viewing the resources on an INGY group object shows:

Groups pre-configured using INGY App

If using a group the has been pre-configured using the INGY App, ensure the group number is MobiusFlow is set equal to the group number of the group previously created in the INGY App.

If a group with a matching group number has been set up within the INGY App, MobiusFlow will automatically pull (given some time) the sceneSetLevel values of any scenes which have already been set up using the app.

The scene number matches the display order shown in the INGY App. As such, the first scene shown in the list on the INGY App is scene 0, the second is scene 1, the third is scene 2, and so on.

Scene Settings

Each lighting group supports 8 different scenes (numbered 0 - 7). These may have been previously set up using the INGY app. MobiusFlow will automatically query the level set point of each scene and will display this in the corresponding knownLevel resource. MobiusFlow can also be used to change each scene's level set point (0% - 100%) by setting that scene's corresponding setLevel resource.

Note that: If the INGY App has been used to pre-set up some scenes, MobiusFlow will still allow you to change these settings. As such, it as advised to adhere to a common source of truth, either configuring all scenes within the INGY App or within MobiusFlow.

It may be possible that the real-world scene setting levels or MobiusFlow have become out of synchronous. This could have been caused if they were changed my something that was not MobiusFlow, such the INGY app or API. To ensure the real-world scene level settings do match the settings within MobiusFlow, set the resendSetLevelCommands (RID 83) to true. Note that MobiusFlow will immediately reset this back to false, whilst also resending the command to set the scene level settings of all scenes.

Changing Scene

MobiusFlow automatically queries which scene is currently being exhibited by the group, and shows this information in the knownScene resource.

Changing the currently exhibited scene on a given group is done in two steps:

1. Set the sceneSetting resource to scene number of the desired scene (if the resource currently shows the desired scene, this step can be skipped)

2. Set the send trigger to true (the service will automatically set this back to false immediately afterwards). This will cause MobiusFlow to command the INGY group to change to the desired scene.

Alternatively, these steps can be handled in one by using the INGY Set Scene flows node.

When configured, this node is pointed at an INGY group object, and will receive an input payload (0 - 7) representing the desired scene number. The node automatically handles the resource changes to cause the group to change scene.

Devices and Querying

MobiusFlow objects can added to represent real-world INGY devices. These objects are used to query and encapsulate the data coming from these devices in addition to control which group a given device is a member of.

Searching ingy in the objects library will display the list of options of MobiusFlow objects that can represent the real-world INGY devices.

Add these options in the correct quantities to represent the INGY devices within MobiusFlow.

Every INGY object type will require the entry of the INGY node address (wirepas address) as well some other information:

If knowing the current lighting level of any lighting device is required, ensure Auto Query Level is checked to ensure MobiusFlow automatically pulls current level data from this device.

INGY Partition

Some INGY nodes can be partitioned to act as separate controllable devices. Represent these partitions using multiple MobiusFlow objects with the same Node Address but different partition numbers. If the INGY node has not been partitioned, the partition number should be set to the default of 0.

Grouping

The known group membership of all devices is automatically queried by MobiusFlow and this data is stored into knownGroupMembership resource.

The group membership of a given device can be changed by setting the setGroup resource. The knownGroupMembership resource should reflect this change after a period of time.

Sometimes it may be required that the command to group a given INGY device needs to be resent. This often can occur if the device is offline with the original setGroup command is sent. In this situation, set the sendRegroup resource to true. Note that, MobiusFlow will immediately set this resource back to false whilst sending the regroup command.

Data

MobiusFlow will automatically pull all possible data from the known INGY nodes into corresponding MobiusFlow objects.

Direct interfacing with INGY API

Two flow nodes have been written to aid direct interfacing with the INGY API.

Note that all INGY flow nodes share the MobiusFlow connection configuration node. If this has not been created already, the node will prompt you to set up the connection between flows and MobiusFlow.

INGY Spy Node

The INGY Spy node is used to view all the coming from INGY gateway. This includes data sent out over the INGY gateway's datastream as well as directly viewing all API commands and responses.

The INGY spy node can be aimed to a given MobiusFlow INGY service within it's config, and set up with debug nodes as shown above. The two outputs map to the datastream and api respectively.

INGY Send API Command Node

The INGY send raw command node is used to send direct API command to the INGY API.

The node must be aimed at a specific MobiusFlow INGY service within the node's configuration.

The node takes input messages who's payload must be formatted to be a valid INGY API command as shown in the INGY API documentation. The response to this command will be outputted from the nodes output.

It is recomendded a function is used to set the command body as shown in the example flow below:

In the above example the code in the function node is a as follows:

msg.payload = {
    version: 85,
    type: "volatile_partition",
    command: "QUERY_CAPABILITIES",
    destination: 'broadcast'
}
return msg;