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 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 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 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 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 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 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 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 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 |