HTTP Control

What HTTP Control Does

HTTP Control lets Universal Devices IoX programs send HTTP requests to devices and services, and exposes numeric response values as ordinary IoX node status fields.

Common applications include querying a temperature sensor, retrieving values from a REST API, triggering a device's HTTP action, or invoking a webhook.

Installation & First Setup

1. Open the PG3x interface for your Universal Devices eisy.
2. Find HTTP Control in the Beta Node Server Store and install it into an available slot.
3. Open the installed node server's Custom Parameters page.
4. Add at least url1_name and url1_url; optionally configure the method, response fields, and polling.
5. Save the parameters and restart the node server to create or update endpoint nodes.
6. Open the IoX Admin Console. If the new nodes or profile labels do not appear, fully close and reopen the console.
7. Select the endpoint node and use Send Request to test it.

Requirements: eisy with PG3x and IoX, plus network connectivity from the eisy to each configured endpoint. The installation script installs the Python dependencies udi-interface and requests.

Custom Parameters

Each endpoint uses a numbered prefix, url1_ through url16_. For example, the second endpoint uses url2_name, url2_url, and so forth.

Replace N with an integer from 1 through 16. A node is created only when both its name and url are present. Its IoX node address is url1, url2, etc.

Entering headers

The header value must be a valid JSON object. For example:

Parameter: url1_headers
Value:     {"Authorization":"Bearer YOUR_TOKEN","Accept":"application/json"}

Header names and values must be enclosed in double quotes. A malformed JSON object causes the request to fail before it is sent.

HTTPS & Authentication

Use https:// in urlN_url for an encrypted connection. The HTTPS server must have a certificate trusted by the eisy, matching the URL hostname.

Username and password (HTTP Basic Authentication)

If the API uses HTTP Basic Authentication, encode the username and password separated by a colon. Run on the eisy (replace these sample credentials):

printf '%s' 'admin:mypassword' | base64 | tr -d '\n'

This example produces YWRtaW46bXlwYXNzd29yZA==. Enter the following as separate PG3x Custom Parameters. The equals signs separate names and values; do not include them in the parameter names.

url1_name = Secure Device
url1_url = https://device.example.com/api/status
url1_method = GET
url1_headers = {"Authorization":"Basic YWRtaW46bXlwYXNzd29yZA=="}
url1_interval = 0

For your actual account, set the url1_headers value to:

{"Authorization":"Basic YOUR_BASE64_VALUE"}

Other API authentication headers

These are header-based authentication methods. Digest authentication and web-form/session logins are not automatically handled by these examples. Consult the device or API documentation for its requirements.

HTTPS certificates and troubleshooting

Certificate verification is normally enabled. Self-signed, expired, untrusted, or hostname-mismatched certificates may produce an SSL error. The documented Custom Parameters do not include a per-endpoint certificate-verification switch. Prefer a valid certificate or an appropriately trusted certificate authority.

An HTTP 401 generally means credentials are missing or invalid; 403 means access is forbidden. TLS errors occur before an HTTP status is received; inspect the PG3x log.

Save Custom Parameters and restart the node server after changing endpoint configuration.

HTTP Methods & Request Bodies

JSON request body

url1_method = POST
url1_headers = {"Content-Type":"application/json"}
url1_body = {"enabled":true,"level":42}

If the body contains valid JSON, HTTP Control parses it and passes it to the Python requests library as JSON. A non-JSON body is passed as raw request data instead.

Plain-text request body

url1_method = POST
url1_headers = {"Content-Type":"text/plain"}
url1_body = start

Reading HTTP Responses

On an HTTP success response (status 200–299), HTTP Control attempts to parse JSON and updates any configured response fields that can be converted to numbers.

Simple JSON object

Response:

{"temperature":35,"humidity":62}

Field mappings:

url1_field1 = temperature
url1_field2 = humidity

IoX Field 1 becomes 35; Field 2 becomes 62.

Nested objects and arrays

Response:

{
  "sensors": [
    {"temperature":35.5,"humidity":62},
    {"temperature":29.0,"humidity":54}
  ]
}

Use dot-separated property names and zero-based array indexes:

url1_field1 = sensors.0.temperature
url1_field2 = sensors.1.humidity

Field 1 becomes 35.5; Field 2 becomes 54. The path starts at the top level of the JSON response; no leading $. is needed.

Plain-text numeric response

If the response body is simply 72.5, use:

url1_field1 = text

The reserved mapping text means “use the entire response body,” strip surrounding whitespace, and convert it to a number. It does not extract a number from a sentence or HTML page.

Numeric conversion rules

• JSON numbers and numeric strings such as "35.5" are supported.
• JSON booleans convert to 1 (true) or 0 (false).
• Missing keys, invalid indexes, objects, arrays, and nonnumeric text cannot populate numeric fields.
• If one field fails to parse, the plugin logs a warning and retains that field's prior value; other valid fields can still update.

Worked Configuration Examples

Enter each line below as a separate Custom Parameter name and value. The = separates the name from the value in these examples; do not include it in the parameter name.

1. Public test: JSON temperature and humidity

url1_name = Temperature Monitor
url1_url = https://httpbin.org/anything?temperature=35&humidity=62
url1_method = GET
url1_field1 = args.temperature
url1_field2 = args.humidity
url1_interval = 60

The test service echoes the URL's query arguments as JSON. Field 1 should read 35 and Field 2 should read 62. This is an example service, not a live sensor.

2. Public test: plain-text number

url2_name = Plain Text Test
url2_url = https://httpbin.org/base64/NzIuNQ==
url2_method = GET
url2_field1 = text
url2_interval = 0

Select the Plain Text Test node and issue Send Request. Field 1 should read 72.5.

3. POST JSON and read the echoed values

url3_name = POST Test
url3_url = https://httpbin.org/anything
url3_method = POST
url3_headers = {"Content-Type":"application/json"}
url3_body = {"temperature":47,"humidity":81}
url3_field1 = json.temperature
url3_field2 = json.humidity
url3_interval = 0

Issue Send Request. The test service echoes the submitted JSON under its json property, so Fields 1 and 2 should read 47 and 81.

4. Local device action or webhook

url4_name = Patio Device On
url4_url = http://192.168.1.50/api/power
url4_method = POST
url4_headers = {"Content-Type":"application/json"}
url4_body = {"state":"on"}
url4_interval = 0

This is a template: replace the example address, path, headers, and body with those required by your actual device. An IoX program can invoke the endpoint's Send Request command to trigger the action. If the device returns no numeric data, response fields can remain unconfigured.

5. Second sensor on the same API

url5_name = Equipment Status
url5_url = http://192.168.1.60/api/status
url5_method = GET
url5_field1 = measurements.temperature
url5_field2 = measurements.pressure
url5_interval = 120

This is also a template. The field paths must match the JSON returned by your device.

Automatic Polling

For a GET endpoint, set urlN_interval to a positive integer number of seconds. A value of 0 disables automatic polling.

url1_method = GET
url1_interval = 60

Polling is evaluated on PG3x Short Poll events (the supplied node server metadata specifies a 30-second Short Poll). Therefore, the configured interval is a minimum elapsed time, not a precise timer. For example, a 45-second interval may not be checked until the next Short Poll.

Each endpoint tracks the time of its most recent request, including manually triggered requests. Manual requests can therefore shift the next scheduled poll.

HTTP Scene Controllers

Each numeric response field can create an independent IoX scene-controller node.

Configuration example

url1_field1 = temperature
url1_field1_controller = true
url1_field1_on = 75
url1_field1_on_operator = >=
url1_field1_off = 70
url1_field1_off_operator = <=

Add the resulting Field 1 node to an IoX scene as a Controller.

Supported operators: ==, !=, >, >=, <, <=.

Operators default to ==. ON and OFF thresholds default to 1 and 0.

The first matching reading sends an ON or OFF event. Further events occur only when the state changes.

Values between thresholds retain the previous state. Before either condition matches, the state is Unknown.

If both conditions match, no event is generated. Failed HTTP requests and invalid fields do not trigger scenes.

Scene Controller Parameters

Use the endpoint prefix urlN_ and field number X (1-8). For example: url2_field3_on.

Hysteresis Example

With ON >= 75 and OFF <= 70:

• 75 or higher: ON
• 70 or lower: OFF
• Between 70 and 75: retain previous state

IoX Scene Setup

1. Enable the desired field controller in Custom Parameters.
2. Save the parameters and restart the node server.
3. Reopen the IoX Admin Console if necessary.
4. Add the new Field controller node to an IoX scene as Controller.
5. Configure the scene responders.

IoX Nodes, Status & Programs

The node server creates a controller node and up to 16 endpoint nodes. Each configured endpoint has a stable address such as url1 and its configured display name.

Endpoint commands

Endpoint status fields

Using a node in an IoX program

In the IoX Admin Console, create a program and use the endpoint's Send Request command in its Then section. For example, a motion or schedule condition could execute the Patio Device On endpoint. To react to returned measurements, add conditions referencing the endpoint's Field 1–8 values.

What happens after errors?

When an HTTP response is received, the HTTP status and response time are updated. An HTTP status outside 200–299 sets Last Request Successful to False and leaves measurement fields unchanged. Connection errors, timeouts, and invalid header configuration set Last Request Successful to False; the code does not reset the prior HTTP status code, response time, or measurements in those cases.

Troubleshooting

Useful diagnostic sequence

1. Temporarily test the endpoint with a known working GET URL.
2. Issue Send Request manually.
3. Check Last Request Successful, HTTP Status Code, and Response Time.
4. Check the node server's PG3x log for request failures or field parsing warnings.
5. Restore your target URL and add response-field mappings one at a time.

Security & Current Limitations

• Prefer HTTPS. Plain HTTP can expose request data and credentials on the network.
• Protect API tokens. Custom Parameters and plugin logs should be accessible only to trusted administrators. Do not put credentials in public GitHub commits or shared screenshots.
• Limit device permissions. Use narrowly scoped tokens and avoid configuring destructive DELETE endpoints unless needed.
• Timeout: each HTTP request uses a five-second timeout.
• No redirect following: configure the final URL instead of relying on 301/302 responses.
• Numeric fields only: response mappings populate numeric IoX drivers; arbitrary strings cannot be displayed in those fields.
• No dynamic command payloads: request URL, method, headers, and body come from saved Custom Parameters.
• Polling is approximate: it depends on the PG3x Short Poll cadence, not a separate per-endpoint scheduler.

Quick Reference

Project: github.com/lovintexas/udi-http-control
License: MIT
Documented release: 1.5.0