Articles in this section

See more

HTTP API Commands

  • Updated

Once your Nero gateway is set up correctly it has the ability to be controlled using an HTTP interface. The below is a brief introduction to the HTTP API, however full documentation is available at the links below:

  • Local API (when controlling NEXUS-NERO on the same network)
  • Cloud API (when controlling NEXUS-NERO remotely)

You will need to have a list of the device and scene IDs for this, please check out this article on how to generate a list of all the IDs in your system.

Run a scene

The command below will activate the specified scene to run.  

Variables:

  • {ip_address}: The IP address of your gateway on the network. We recommend you use static addresses or DHCP reservations to ensure this does not change.
  • {scene_number}: The ID of the scene you wish to run.

URL:

http://{ip_address}:3480/data_request?id=lu_action&serviceId=urn:micasaverde-com:serviceId:HomeAutomationGateway1&action=RunScene&SceneNum={scene_number}

Controlling a device

Controlling a device directly requires a few more variables to let it know whether it is turning on, off, dimming, etc.

Variables:

  • {ip_address}: The IP address of your gateway on the network. We recommend you use static addresses or DHCP reservations to ensure this does not change.
  • {device_number}: The ID of the device you wish to control.
  • {light_level}: The light level you wish to set the device to (dimming devices only). This value can be between 0 and 100
  • {relay_state}: Whether you want the device to turn on (1) or off (0) (relay devices only).

URL (relay devices):

http://{ip_address}:3480/data_request?id=lu_action&output_format=json&DeviceNum={device_number}&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue={relay_state}

URL (dimming devices):

http://{ip_address}:3480/data_request?id=lu_action&output_format=json&DeviceNum={device_number}&serviceId=urn:upnp-org:serviceId:Dimming1&action=SetLoadLevelTarget&newLoadlevelTarget={light_level}

Special whole-system commands

There is a special device, with the ID 999, that allows you to send commands to all of the devices in your system. The main use for this is to access the All On and All Off lights command from the Quick Commands in the My Nero dashboard. You can also send other commands this way but this isn't recommended or supported.

Turn all lights on

http://{ip_address}:3480/data_request?id=lu_action&Category=999&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=1

Turn all lights off

http://{ip_address}:3480/data_request?id=lu_action&Category=999&serviceId=urn:upnp-org:serviceId:SwitchPower1&action=SetTarget&newTargetValue=0

Exploring the API in depth

There are a lot more options in the API than we can document easily. You can explore the entire available API for any device in your system using the Advanced Scene Editor. To access the editor, open any scene (or create a new one) and under Step 3, select Advanced Editor.

advanced_editor.png

Understanding the structure of a command

A command in the Nero API is made up of a series of segments, all of which are shown in the advanced editor. If we take an example command with each segment replaced with a placeholder we can start to understand the way it works:

http://{ip_address}:3480/data_request?id=lu_action&output_format=json&DeviceNum={device_number}&serviceId={service_profile}&action={action}&{action_name}={desired_state}

  • {ip_address}: The IP address of your gateway on the network. We recommend you use static addresses or DHCP reservations to ensure this does not change.
  • {device_number}: The ID of the device you wish to control.
  • {service_profile}: The type of service we want to interact with. There are a lot of different service profiles in the Nero system, all of them in a format similar to this one for a Power Switch: urn:upnp-org:serviceId:SwitchPower1. You need to have the correct service profile to access its actions.
  • {action}: The name of the action that you want to invoke. For most interactions with the API this is likely to be SetTarget.
  • {action_name}: For actions with additional options, such as setting a dimming level or turning a device on or off, you need to provide the action name that you want to invoke combined with the desired state. To turn a light on or off for example this would be newTargetValue.
  • {desired_state}: The state you want the device to change to. For most devices, this will be 1 or 0 or a number between 0 and 100 for dimming level.
    • NOTE: The advanced scene editor will show True and False options for a lot of binary actions, such as SetTarget. You can't provide True and False to the API, so you need to convert there to their numeric versions. True (on) is represented as 1 and False (off) is represented as 0.

editor_key.png

drop_down.png 

 

Use this editor to piece together the commands you want to issue remotely. It is also a very useful way to test that the commands you want are correct by simply running the scene and checking it worked as expected.

Need some assistance?

If you need some assistance with creating API requests, please submit a request with us from the request button or using the Help button in the lower right and we will help out. Don't forget to provide your tech support code so we can access your gateway and system profile.