CW's IDIOT GUIDE - To Ezlo platform HTTP API commands aka Luup Requests

[cw-kid]

Credits to @reneboer @crille @blacey

Also see the “Ezlo Linux firmware - HTTP documentation preview” here

PART 1 - Running scenes with authentication turned on

OK after a lot of trial and error and help from some of you guys on the forum, I now have basic control of devices and scenes working via HTTPS commands.

In Vera as you may know we had the Luup Requests API where we could easily send simple one line HTTP commands to Vera to control devices, run scenes and set device variables etc.

This was very useful for all sorts of things and integrations with different devices and apps on your local LAN.

In Ezlo we now have similar functionality but it is much more difficult to get working, at least for me hence the Idiots Guide…

By default the Ezlo hub will require a username and token (password) and will use HTTPS.

You can now turn off the authentication to enable you to use more simple one line HTTPS commands similar to Vera Luup Requests.

Scene example with authentication turned on:

If you wish to leave authentication turned on you will need to use this Python script here to get your token from your Ezlo hub / Ezlo cloud.

@Oleh I don’t think we know yet how long these tokens last for? Or when they will expire?

I am using my Raspberry Pi for testing all this. Using WinSCP on my Windows 10 laptop I uploaded the Python script “Ezlo_create_curl_config.py” to my Pi into my “Ezlo” directory.

Then using Putty and SSH connecting to the Pi, I ran this command to get my token for my Ezlo Plus hub:

python3 Ezlo_create_curl_config.py HubIP HubSerialNumber Username Password

Note: It’s your regular Vera account username and password you use here.

If it works you will get a long token string copy all of this to a notepad for later.

Note: If it doesn’t work and you get no token given back, remove your Ezlo Plus hub from your Vera account and add it back in again. I had to do this to get my token.

On the Pi I then created a file to store my token called “ezlo_plus_curl_auth” in my “Ezlo” directory, and pasted in the token to this file. It should look something like this:

Now we can use CURL to test it’s working, enter the IP address of your Ezlo Plus hub.

curl -K ezlo_plus_curl_auth https://192.168.0.11:17000/v1/method/hub/info/get

You should get an output like this if it works with the hub info:

Now we need to use the online API tool to find out some scene ID numbers, so we can try and run a scene via HTTPS command line.

Go to Ezlo API Tool and login with your Vera username and password.

UPDATE: They have redesigned the webpage layout somewhat. The “Api Calls” is now called “Commands” and the “Query” button is now called “Send”.

Select your Ezlo hub’s serial number and click the Connect button.

Then from the API Calls drop down list select hub.scenes.list and press the Query button.

Scroll down to the Response section and this will list all the scenes on your Ezlo hub.

You can expand them to find the scene you are looking for:

I want to run my “Turn On Diffuser” scene via HTTPS command line, make a note of the scene’s _id number.

In this example its: “5f4d6a2f120bab10a13b6916”

Now we can construct our HTTPS command to run in Curl.

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/scenes/run?sceneId=5f4d6a2f120bab10a13b6916

Running the scene command in Curl:

Your scene should have run if it worked OK !

That’s it for now more to come later…

[cw-kid]

PART 2 - Running scenes with authentication turned off

If you can’t be doing with all the hassle of auth tokens you can turn off authentication.

Don’t port forward your Ezlo hub from the Internet (WAN) to the LAN however. This is really only for internal use on your LAN.

To turn off authentication we have to go back in to the online API tool Ezlo API Tool login with your usual Vera account username and password.

Select your Ezlo Hub’s Serial number and click the Connect button.

In the “Commands” drop down select “hub.info.get” and press the Send button.

Scroll down to the “Response” section and expand “Result”.

You should see that “offlineAnonymousAccess” and “offlineInsecureAccess” are set to false.

Now in the “Commands” drop down list select “Misc” and “Custom”.

In the text box enter this code:

{
"method": "hub.offline.anonymous_access.enabled.set",
"id": "12345",
"params": { "enabled": true }
}

And press the Send button.

If you want to be able to send HTTP commands rather than HTTPS, then enter this code in to the “Misc” and “Custom” text box and click the Send button again.

{
"method": "hub.offline.insecure_access.enabled.set",
"id": "12345",
"params": { "enabled": true }
}

If you now select hub.info.get again from the “Commands” drop down list and hit the Send button you should see that both of these items are now set to true.

Congratulations you have now turned off Authentication for HTTP API requests.

Scene example with authentication turned off:

OK so now we can try a HTTP command when auth is turned off.

So using our scene example from Part 1 we can try a Curl command but this time without having to specify authentication.

HTTPS COMMAND EXAMPLE:

curl --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/scenes/run?sceneId=5f4d6a2f120bab10a13b6916

HTTP COMMAND EXAMPLE:

curl --http1.1 http://192.168.0.11:17000/v1/method/hub/scenes/run?sceneId=5f4d6a2f120bab10a13b6916

Your scene should of run if it worked OK.

Now because we are no longer using authentication I can run this HTTP or HTTPS command from anywhere on my LAN.

For example I can just enter this in to my Chrome web browser and the Scene is run.

HTTPS:

https://192.168.0.11:17000/v1/method/hub/scenes/run?sceneId=5f4d6a2f120bab10a13b6916

HTTP:

http://192.168.0.11:17000/v1/method/hub/scenes/run?sceneId=5f4d6a2f120bab10a13b6916

If you want to send the HTTP / HTTPS command from a Scene on your Vera hub to the Ezlo hub then you could use a luup.inet.wget command such as this:

luup.inet.wget("https://192.168.0.11:17000/v1/method/hub/scenes/run?sceneId=5f4d6a2f120bab10a13b6916",5)

[cw-kid]

PART 3 - Controlling a device with authentication turned on

Note: If you want to create some virtual devices on you Ezlo controller so you have more devices to test with, see here.

See Part 1 first on how to get your auth token.

Here are some HTTPS command examples for turning on a Z-Wave appliance plug.

Here we are using value_bool=true

curl -K ezlo_plus_curl_auth --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_bool=true"

Or alternatively we can also use this command using value_int=1 to turn on the plug:

curl -K ezlo_plus_curl_auth --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_int=1"

Here are some HTTPS command examples for turning off a Z-Wave appliance plug.

value_bool=false

curl -K ezlo_plus_curl_auth --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_bool=false"

or alternatively using value_int=0

curl -K ezlo_plus_curl_auth --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_int=0"

OK lets try these ON / OFF commands in Curl from the Raspberry Pi:

Your appliance plug or device should be turned on and then off.

How to find your devices ID number?

So in our HTTPS commands to control the device we need to specify the devices item object _id number.

To find out what this ID number is? We need to use the online API Tool again.

Go to Ezlo API Tool and login with your Vera username and password.

Select your Ezlo Hub’s Serial number and click the Connect button.

From the Calls API drop down select “hub.devices.list” and hit the Query button.

Scroll down to the “Response” section and expand “Result”.

You will then see all your devices listed you can expand them further to see what the devices are.

For example here you can see my Everspring appliance plug.

Make a note of the _id number in this example its “5f4e5871120bab1069c13c49”

Now in the Calls API drop down list select “hub.items.list” and hit the Query button.

EDIT: Better to select the hub.items.list - filter by device ID and enter the devices ID. It will then only return the items for that particular device.

Go to the “Response” section again and expand “Result” and then “Items”.

Now I only have two Z-Wave devices paired to my Ezlo Plus the Everspring appliance plug and an Everspring door contact sensor.

Yet I can see 7 item objects.

Each physical device can have multiple “item objects”.

So if I start expanding these item objects I have discovered that my Everspring appliance plug has 4x item objects.

Note: I know I am looking at the right device I want because its “deviceid” is the same as the one we saw earlier when using the “hub.devices.list” query e.g. “5f4e5871120bab1069c13c49”

Here you can see the 4x item objects for my Everspring plug:

Basic -

Switch -

electric_meter_watt

electric_meter_kwh

So now knowing this, I now need to use the correct item object to control the ON / OFF via HTTPS commands.

In this example I can use either “switch” or “basic”.

Lets use “swtich”.

It’s here on this “switch” item object we find the correct _id number we need to use in our HTTP commands

In this example its “5f4e5871120bab1069c13c4c”

So if we look at one of our HTTPS commands again we can see we have the same _id in that command:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_bool=true

Controlling a Dimmable Light or Device

To control the dim value of a device we can use “value_int=” and then a percentage e.g. “value_int=50” to dim to 50%

Using the “hub.items.list” query in the API Tool we can see that a dimmable light has 5x items.

In this example I am using the “Dimmer” item and its _id number.

Example Curl command using Auth to dim to 50%

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f58c63a120bab1065bc0e7e&value_int=50

Example Curl command no Auth to dim to 50%

curl --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f58c63a120bab1065bc0e7e&value_int=50

Example HTTPS command no Auth to dim to 50%

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f58c63a120bab1065bc0e7e&value_int=50

[cw-kid]

PART 4 - Controlling a device with authentication turned off

OK so if you haven’t already you need to follow Part 2 and turn off the authentication for the HTTP API.

See Part 3 for how to find the devices item object _id number.

Now you have done that we can issue HTTPS commands to control our device, in this example an Everspring appliance plug, so we will be using ON and OFF commands.

Here are some example Curl HTTPS commands with no auth:

Turning on the plug:

curl --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_bool=true"

or alternatively we can use this command:

curl --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_int=1"

Turning off the plug:

curl --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_bool=false"

or alternatively we can use this command:

curl --http1.1 --insecure "https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_int=0"

Now because we have authentication turned off we can issue these HTTPS commands from any device or app on our LAN.

For example in the Chrome web browser on my laptop I can just enter these commands for ON / OFF:

Turning plug on via Chrome browser:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_int=1

Turning plug off via Chrome browser:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f4e5871120bab1069c13c4c&value_int=0

[cw-kid]

PART 5 - Testing with Postman GUI application

Postman is a desktop application for Windows, MacOs and Linux for testing API’s for sending requests and viewing responses.

You can create different “Collections” and “Requests” in the menu on the left hand side.

You enter your HTTPS command in the Send field and the response can be seen below.

In this screen shot you can see the response is “Status 200 OK” for a run Scene command.

Controlling a device example.

To configure Postman to use authentication or no authentication:

No auth:

With auth:

Select “Basic Auth” from the drop down list and enter your Vera account username and your password token string.

[cw-kid]

PART 6 - OTHER CONTROL COMMANDS

1. Armed / Disarm a device.

Example Armed Command:

https://192.168.0.11:17000/v1/method/hub.device.armed.set?_id=5f4e588c120bab1069c13c4f&armed_bool=true

Curl with no auth:

curl --insecure --http1.1 “https://192.168.0.11:17000/v1/method/hub.device.armed.set?_id=5f4e588c120bab1069c13c4f&armed_bool=true”

Example Disarmed Command:

https://192.168.0.11:17000/v1/method/hub.device.armed.set?_id=5f4e588c120bab1069c13c4f&armed_bool=false

Curl with no auth:

curl --insecure --http1.1 “https://192.168.0.11:17000/v1/method/hub.device.armed.set?_id=5f4e588c120bab1069c13c4f&armed_bool=false”

The easiest way to discover the correct deviceid _id number is to use the online API tool and watch the “Broadcast response - Hub’s latest broadcast messages” section.

Go to Ezlo API Tool and login with your Vera username and password.

Select your Ezlo Hub’s Serial number and click the Connect button.

In the Vera Mobile app press the “Armed” button on the device you want to construct a HTTPS command for.

Watch the Broadcast section for the response.

You will see a response like the above screen shot. Copy the _id number this is the one to use in your HTTPS command.

2. Turn ON / OFF a Switch. (This is a virtual switch on my Ezlo Plus)

Again the easiest way to discover the correct deviceid _id number is to use the online API tool and watch the “Broadcast response - Hub’s latest broadcast messages” section.

Turn on the switch you want to control via the HTTP API and look for its item object _id number. In this example its “5f57d92f120bab1065bc0e76”

Command with no auth to turn on the switch:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d92f120bab1065bc0e76&value_bool=true

OR

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d92f120bab1065bc0e76&value_int=1

Command with no auth to turn off the switch:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d92f120bab1065bc0e76&value_bool=false

OR

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d92f120bab1065bc0e76&value_int=0

3. Trip and Un-trip a motion sensor. (This is a virtual motion sensor on my Ezlo Plus)

To find the correct item object _id number for this motion sensor I had to use the “hub.items.list” query in the online API tool, in this example its “5f57d230120bab1065bc0e74”

Command with no auth to trip the motion sensor:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_bool=true

OR

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_int=1

Command with no auth to un-trip the motion sensor:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_bool=false

OR

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_int=0

The eagle eyed are probably noticing by now that the commands are the same for the switch and motion sensor, we are just changing the devices item object _id number to the device we want to control !

4. Controlling Ezlo House Modes (Home / Night / Away / Vacation).

Using the online API Tool we can use the “hub.modes.get” query to list our house modes and see their ID numbers.

Looking in the “Response” section and the “Result” we can see the first House Mode item object:

Home = _id “1”

Away = _id “2”

Night = _id “3”

Vacation = _id “4”

OK so now we know the _id numbers for each of the different House Modes, lets look at switching the modes via HTTPS commands, for this we can use “hub.modes.switch”.

NOTE: This only works when using the token authentication:

EDIT: Seems you can switch House Modes with no authentication, I rebooted my Ezlo Plus and then it started working with no auth.

Curl HTTPS command using Auth - HOME MODE

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/modes/switch?modeId=1

Curl HTTPS command using Auth - AWAY MODE

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/modes/switch?modeId=2

Curl HTTPS command using Auth - NIGHT MODE

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/modes/switch?modeId=3

Curl HTTPS command using Auth - VACATION MODE

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/modes/switch?modeId=4

Curl HTTPS command using Auth - CANCEL HOUSE MODE SWITCHING

Using this command you can cancel the switching to another house mode.

curl -K ezlo_plus_curl_auth --http1.1 --insecure https://192.168.0.11:17000/v1/method/hub/modes/cancel_switch?modeId=1

How to increase the “hub.modes.alarm_delay.set” and “hub.modes.switch_to_delay.set”

These are not HTTPS commands however we can use the API Tool to set these delays in seconds, the default is 30 seconds. I have set both of these to 120 seconds.

5. Control Roller Shutter / Window Covering.

A Roller Shutter devices “dimmer” value 0 to 100 can be controlled.

In the API Tool first use the “hub.devices.list” query to find the _id number of the Roller Shutter device.

Next use the “hub.items.list” query to find the correct device item object for this Roller Shutter device.

There are several device item objects for a Roller Shutter device, the one we want to use is the “dimmer” item.

Example HTTPS command to set a Roller Shutter to 50% with no Auth.

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f5b7a69120bab1066107b8f&value_int=50

6. Controlling a Thermostat’s Set Point value.

In the API Tool first use the “hub.devices.list” query to find the _id number of the Thermostat device.

Next use the “hub.items.list” query to find the correct device item object for this Thermostat device.

The device item object we want to use is “thermostat_setpoint”.

Example HTTPS command with no Auth to set the Thermostat set point to 23 degress.

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f5b78bc120bab1066107b87&value_int=23

Example HTTPS command with no Auth to set the Thermostat set point to 10 degress.

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f5b78bc120bab1066107b87&value_int=10

There are also some other device item objects for a thermostat device such as:

thermostat_setpoint_heating
thermostat_setpoint_cooling

However when I tried to send values to these items it did not work and those set points did not change, even though I received no error in Postman.

There is also a thermostat item named “thermostat_mode” with these possible modes by the looks of it. However I don’t currently know the correct commands to use for setting these modes?

0: “off”
1: “heat”
2: “cool”
3: “auto”
4: “aux”
5: “resume”
6: “fan_only”
7: “furnace”
8: “dry_air”
9: “moist_air”
10: “auto_change_over”
11: “saving_heat”
12: “saving_cool”
13: “away_heat”
14: “away_cool”
15: “full_power”
16: “special”
17: “eco”
18: “emergency_heating”
19: “precooling”
20: “sleep”

[Pitt13]

Hi
thank you for this guide, we are still very far from simple things like I descative the authentication via a button on the interface and I create the http request simply with an ID and a parameter.
For me it’s too complicated at the moment to do all this, mounted a Pi, create this, create that, two machines that also run, one that crashes and it’s the loose

[cw-kid]

I’ve updated the guide with the first 4 parts for controlling a device or running a scene, either with authentication turned on or with authentication turned off.

[reneboer]

Hi @cw-kid,

Very nice write ups. Well done.

Cheers Rene

[kigmatzomat]

This is very good and the kind of materials ezlo should producing.

Does it support requesting device status? That would allow better integration with NodeRed and the like.

[cw-kid]

@kigmatzomat

Does it support requesting device status?

Not sure yet but I would expect so. I haven’t seen any example commands for setting or getting a devices variable / status.

[therealdb]

@kigmatzomat

Does it support requesting device status? That would allow better integration with NodeRed and the like.

Yes. There’s a doc in a previous thread with available calls. @reneboer has some samples in its python script, if I remember correctly.

[Ioana]

Thank you @cw-kid !

I’ve create an article with the information provided, so everybody can access it. I’ve posted it here as well.

[cw-kid]

@Ioana

I’ve updated Part 3 and confirmed that the commands work for a Dimmable Light.

And I’ve updated Part 6 for controlling House Modes and for tripping / untripping a motion sensor.

They will be continued to be updated as and when we discover new HTTPS commands.

[Ioana]

Great! Please ping me/send a dm whenever you update the info, so I’ll make sure we’re using the latest and greatest in the webpage as well

[eonnet]

@cw-kid

3. Trip and Un-trip a motion sensor. (This is a virtual motion sensor on my Ezlo Plus)

To find the correct item object _id number for this motion sensor I had to use the “hub.items.list” query in the online API tool, in this example its “5f57d230120bab1065bc0e74”

Command with no auth to trip the motion sensor:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_bool=true

OR

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_int=1

Command with no auth to un-trip the motion sensor:

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_bool=false

OR

https://192.168.0.11:17000/v1/method/hub.item.value.set?_id=5f57d230120bab1065bc0e74&value_int=0

Hello @cw-kid and @Oleh i tried this command and something is not working.
when i trip the virtual sensor it does not change state in the UI in the app, so i don’t know if its tripped or un-triped. I armed the sensor so at least i can have a notification to see if its working and when i trip the sensor nothing happens but when i un-trip the sensor i receive a notification that movement is no longer detected.

is it a bug or this is a case only with me?

[Crille]

I’m having the exact same issue so I would say a bug.

[cw-kid]

When I tested the virtual motion sensor in the Vera mobile app for Android you could see that it was tripped by the icon flashing.

I have not tested notifications.

I know there is a bug where I was unable to disarm a device by https command. But I could arm the device OK.

[Crille]

So it’s an Android vs iOS thing then again

[eonnet]

i’m on IOS also