iLight lighting system API calls

Hi

Are there any instructions on making API calls to another system? I would like to connect to an iLight lighting system using the ethernet gateway EG2-s on the local network which uses WebSockets and JSON Remote Procedure Calls (RPC), version 2.0. Details below thanks in advance.

The URL to an EG is: wss:///eg/

The EG2-S generates a new 2048-bit RSA private key and X.509 certificate when first run. This may be read from the device using the ReadCertificate command on the EG2-S model element and is returned in PEM format. A new certificate may be generated at any time using the GenerateCertificate command and must be
done after changing the hostname. A reboot is required to use the generated key and certificate.
Once connected, all RPCs within this document take the following JSON format:

{
ā€œjsonrpcā€:ā€œ2.0ā€,
ā€œidā€:,
ā€œmethodā€:,
ā€œparamsā€:
{
<argumentsā€¦>
}
}

Welcome!

I good first stop for third party systems that are working with Home Assistant is this searchable database, link below.

That said, a quick ā€˜cheekyā€™ look at the iLight web site leads me to think they are not going to be really an ā€˜openā€™ system. Again looking at their web site, with words like ā€˜bespokeā€™ on it, I think you have already sent them your ā€˜first bornā€™ to get in the door :wink: .

Again, just a quick look at there stuff, it does seem to be based (at least in part) on a fairly well known and documented (that does not however imply ā€˜openā€™) lighting system/protocol called DALI.

Yes, there are methods in and around Home Assistant to interface with many yet to be adapted systems using technologies such as web sockets and RPCā€™s. So if your system has ā€˜openingā€™ that allow third parties to interface, you may be able to interface Home Assistant to your system. If you have any links to publicly available documentation on your iLight system, sharing that here may help you find folks that can advise.

Do some searching on this forum, Github and the internet in general for ā€˜Home Assistant and DALIā€™, you might find some folks with experiences of use to your environment.

Unfortunately for ā€˜openā€™ interfacing, many high end lighting system do use encryption to keep their ā€˜walled gardenā€™ system to themselves. There can be good reasons for this from a security, safety and privacy standpoint. But, this is often ā€˜in the faceā€™ of working with other systems.

Good hunting!

Hi

Thanks for the reply. I actually work for iLight - thatā€™s why I have the system. The EG2-s has an API which I would like to test more and as Iā€™ve just started out with HA thought it would be a good test and hopefully I get integrated lights as well. The system is does any lighting protocol phase, 1-10v, dali etc. protocol doesnā€™t matter as you call scenes or channel levels via the API.

Ahā€¦ it was not your ā€˜first bornā€™, it was your ā€˜soulā€™, you work for them grinā€¦

From the EG2-S web page, this is all I find:

ā€˜For programming EG2-S, Device Editor software is required.
Please consult your iLight representative for latest versions.ā€™

As I said, if you can share more publicly available documentation on options to interface, this will help folks advise you.

And I am not sure I understand your words here :
ā€˜The system is does any lighting protocol phase, 1-10v, dali etc. protocol doesnā€™t matter as you call scenes or channel levels via the API.ā€™

Good hunting!

1 Like

You can likely use a RESTfull sensor
But obviously, you have to actually know the ā€œmethodā€ and ā€œparamsā€ that needs to be sent to the API endpoint.

That wonā€™t work over a websocket (wss://) though.
If you donā€™t have a https:// endpoint, youā€™ll have to develop a dedicated integration.

1 Like

I would be that iLight rep. The system is all setup thatā€™s the Device editor bit. The source controllers (These actually control the lights) SCMDx for dali, SCMI0402 for mains diming etc. respond to Scene or channel messages sent via the iCANnet network. The EG2-s sits on ethernet and iCANnet and provides the API integration.

What I need to know is how or where you make the connection in HA. Below is part of the API documentation.

Ethernet Gateway API

Introduction
This document contains the Application Programming Interface (API) detail to control communication and
bridging with the next generation Ethernet Gateway (EG) devices. The purpose of the communication, and the
scope of this document, is to allow the transmission and receipt of Controller Area Network (CAN) messages
to iLight devices. The iLight CAN properties are not defined within this document. Bridging allows the
forwarding on CAN messages to another CAN network, controlled by an equally capable EG.
All communication uses WebSockets and JSON Remote Procedure Calls (RPC), specifically version 2.0.
The URL to an EG is:

wss:///eg/

The EG2-S will generate a new 2048-bit RSA private key and X.509 certificate when first run. This may be read from the device using the ReadCertificate command on the EG2-S model element and is returned in PEM
format. A new certificate may be generated at any time using the GenerateCertificate command and must be
done after changing the hostname. A reboot is required to use the generated key and certificate.
Once connected, all RPCs within this document take the following JSON format:
{
ā€œjsonrpcā€:ā€œ2.0ā€,
ā€œidā€:,
ā€œmethodā€:,
ā€œparamsā€:
{
<argumentsā€¦>
}
}
The deviations from the JSON RPC 2.0 specification are:

ā€¢ should be a UUID, in string format, but an integer will also be accepted.

ā€¢ ā€œparamsā€ must always be a JSON object. Therefore, {} is expected if no arguments exist for the RPC.
The prototypes in this document take the following format:

(

):

Arguments are expressed as a comma separated list of zero to many names and types (taking the format : ). Details of types may be in the Types section.
The example below will transmit a CAN message with a zero identifier and a single zero value byte of data.
With the prototype and JSON representation following respectively:
Transmit(
id: Integer<$000ā€¦$7FF>,
data: Array<Integer<$00ā€¦$FF>>
):String
{
ā€œjsonrpcā€:ā€œ2.0ā€,
ā€œidā€:ā€œdbbcab75-d992-4a1c-9e26-9f28d352656cā€,
ā€œmethodā€:ā€œTransmitā€,
ā€œparamsā€:
{
ā€œidā€:0,
ā€œdataā€:[0]
}
}
Page 6 of 19
Ethernet Gateway API
Classified
Remote Procedure Calls
Execute
Prototype
Execute(
id: UUID,
command : String,
args : Object
): Value
Description
Execute the command, with args, on the target identifed by id. The commands available and arguments
required and returned value will depend on the version and type of the target. The data model provides
information on available commands. This is only possible once the client has logged into the EG.
Log In
Prototype
LogIn(
username: String,
password: String
): String
Description
Log in to the EG device as username with password to allow communication on CAN and configuration of the
device. The default username and password are ā€œcommissionerā€ and ā€œpasswordā€. It is not possible to use the
default password to log into the API, the password should first be changed using the SetPassword RPC.
Log Out
Prototype
LogOut(): String

Set the level of all channels in the area to level over fade milliseconds.
SetScene(
scene: UUID,
fade: Integer<0ā€¦3600000>
): String

Thanks Iā€™ve got the calls the API needs but it was how to implement them over wss that I hadnā€™t found.

As @koying writes. I do not think there is a built in way to make a web socket wss: call in the Home Assistant backend system. Weirdly, I think I remember playing around with making wss: calls from the front Lovelace user interface a while back. Not sure, even if that is still possible, that would be the way you would want to us web sockets to interface between Home Assistant and your controller.

I searched, but did not find any example of how to do a web socket call in the same way you can do a http: or https: call from Home Assistant. However, perhaps if you asked the specific question of ā€˜how do a make a web socket call to an external APIā€™ here on this forum, with examples of your JSON data and even better if you have example of code from your system documentation on how to make these calls.

Good hunting!

1 Like

Iā€™m pretty 99.99% sure there is no out-of-the-box solution.
Considering the event-driven architecture of HA, and the connection-oriented nature of WSS, Iā€™m pretty convinced there is no way at all, actually.

1 Like

Oh well ASCII it will have to be then. Shame as its not got as many functions.

Thanks