Package: HTTP Server

Author: HCA Central
Version: 6
Added to Library: 13-Nov-23
HCAVersion needed: 18.0.10
Keywords: Utility

Requirements: Defined one of the 8 interfaces (hardware tab of HCA Options) as a "Generic Server" for port 80. The configuration is:

Port: 80

Data: Text

Delimiter for Sent to: None

Delimiter for received from: None

Package Description:
What's new?

8-Nov-23

Added the ability to create a log of Hubitat messages. See the program notes in the program "Hubitat Log" to see how this can be configured

17-Oct-23

1. The ReceiveHTTP program now saves as a tag on the program the IP address and time of last reception received

2. The ReceiveHTTP program now processes the /ReportHubInfo op

4-Nov-22

1. Added the ability for the action operations /state, /on, /off, and /setPercent to either return a HTML or a JSON result.

-- With no configuration set then replies are in JSON format

-- Add the tag "MakeHTMLReplies" to the "Receive HTTP" program to generate HTML replies and also include the tag "HTMLTextSize" to set the size of the text in the reply

2. It is assumed that using the HTTP interface to control a device is analogous to controlling the device locally so the device "Last Reception time" is changed to the current time for the on, off, set-percent, and state operations. Note that this only happens for HCA 17.0.49 or later

Older:

1. Added the ability for users to add their own HTTP commands called "HTTP Extensions"

3. Added /on /off and /SetPercent as shorthand for /state

Program: Build design json

Program Description:
Creates JSON that lists all the devices in a design. Each JSON array element shows an ID, name, and capability. The Id will be fixed in the design and can be stored and used as needed.

Return value: A string in JSON format which is the design as described above

Parameters:

Name Type Description Default
Tag Value If not an empty string then only those objects that contain this tag are returned  

Program: Create error result

Program Description:
Creates an error Result in JSON format

Return value: JSON format

Parameters:

Name Type Description Default
Code Value error code  
Description Value error description  

Program: Find HTTP Extension

Program Description:
Supplied with the text of the operation extracted from the URL, finds the program that has a tag with name "HTTP Extension" and tag value the text of the operation.

Parameters:

Name Type Description Default
op Value Operation extracted from URL  

Program: GetParameter

Program Description:
Given a URL with parameters, finds the value for a named parameter.

The URL is expected to be structured as: <stuff>?name1=value1&name2=value2&name3=value3

Return value: A BOOL result if the parameter is not found. If found the parameter value as a string.

Parameters:

Name Type Description Default
url Value URL  
name Value Name of parameter  

Program: GetTarget

Program Description:
Looks for ?id=x or ?name=x and returns X if found or No if not

What comes after the id= is the internal fixed id of the object For example ?id=10002

What comes after the name= is the two part name of the object. For example ?name=office-lamp

Example:
Looks for ?id=x or ?name=x and returns as a string either the value of "Id" or the value of "Name". It is assumed that either Id or Name will be given but not both.

Return value: String value is parameter found, Bool value if not found.

Parameters:

Name Type Description Default
opWithParameters Value operation part of the URL with all parameters  

Program: Hubitat Log

Program Description:
Creates a log of the commands received from the Hubitat. These commands are initiated by the HCA device drivers and HCA App.

Configuration is by two tags on the "HTTP Receive" program:

HubitatLog

Set the value to 0 to disabled logging, and 1 to enable logging

HubitatLogPath

Path to the file to create the log. If the path contains in the filename the string MM_DD then that is replaced by the 2-digit month and 2-dight day. For example:

HubitatLogPath set to c:\hcafiles\Hubitat_MM_DD.csv

Creates the file c:\hcafiles\Hubitat_11_08.csv on November 8th.

Parameters:

Name Type Description Default
Path Value Path to the log file. If contains MM_DD that is replace dby the month and day  
Command Value Command from the Hubitat  
Info1 Value Command argument  
Info2 Value Command argument  

Program: Hubitat Log Device Name

Program Description:
When the Hubitat HCA device drivers send to HCA commands that effect devices they can send the name of the device either as a 2-part name or by a "U" followed by the fixed id of the device.

Ths program converts the "U" plus fixed id into the 2-part name of the object.

Parameters:

Name Type Description Default
Name Value Object reference sent from the Hubitat  

Program: Receive HTTP

Program Description:
Handles HTTP receptions on port 80 via a Generic Server interface. The implemented requests are:

/api/v1/state?id=<id>&level=<0-100>

Change the state of a device to a percentage. Caan also be given as /setPercent rather than /state

If no error in execution, empty JSON {} is returned

.api/v1/on?name=<id>

Controls the target ON

.api/v1/off?name=<id>

Controls the target OFF

/api/v1/poll?id=<id>[&query=0|1]

Poll a device for state and return its state as a percentage, 0=off, 100=on, percentage otherwise

If the optional query parameter is not present, or it is used and the value is 0, then HCA internal state is used. Otherwise the device is polled if possible and the state received is reported

In the previous two commands the "id" parameter can instead be supplied as a "name" parameter where the two-part name is given. If there are blanks in that name they must be replaced by %20 as in any URL. for example if the device is named "desk lamp" and in the "office" room:

/api/v1/state?name=office-desk%20lamp&level=100

/api/v1/getdesign[?tag=<tagname>]

Returns a JSON encoded string showing each device in the design with name, id, and properties. If the optional tag name is provided then only those objects marked with that tag name are listed in the result.

/api/v1/hcastatus

returns HTML encoded result which is the same as the HCA daily report configured from the tools ribbon category

/api/v1/getfile?localpath=<path>

Loads the named file - must be in the HCA folder in your documents area - and returns the contents as a plain text file

/api/v1/ReportHubInfo?Info=text

This is a message sent from the Hubitat HCA App reporting info that was requested. The text is saved in the global variable HE_HubVersion

Return value: Possible errors are:

99 - Not yet implemented

100 - request not properly formatted

101 - request doesn't start with /api

102 - version 1 requests only supported

103 - Not a valid operation

200 - Necessary parameters for an operation not provided

201 - Operation failed

Parameters:

Name Type Description Default
Received Value Data received  
FromIPAddress Value IP address of the source of what was received  

Global Variable Use:

Name Description
FriendlyDesignData Since the JSON is asked for bock-by-block, holds the current design data so subsequent block retrievals can access the block requested.
HE_HubVersion Firmware version of the Hubitat hub
HE_HubAddress IP Address of the Hubitat Hub