Hubitat Nubie Trying to Call a Hubitat App from a Third Party System

jbasen · March 21, 2020, 1:30am

Hi

I am brand new to Hubitat so please be patient with me. I have been using a SmartThings hub to make Z-Wave and Zigbee devices available to a Crestron professional automation processor. This uses a combination of groovy code on the SmartThings hub and C# code running on the Crestron processor. My goal is to port this to Hubitat.

Because I am brand new to Hubitat I have some very, very basic questions. I’m hoping that as I get one or two things working I’ll be able to make my way through the rest of it. But the learning cliff of working with a new system is always challenging.

I found the Maker app and in actuality what I’m trying to accomplish is very similar. The one part that is different is that the groovy code I’m porting from SmartThings will call the Crestron system with updates when the status of a device changes; such as when a user turns a light on/off at a wall switch.

For example, one of the Maker calls is:

http://Hubitat_IP/apps/api/34/devices/[Device ID]?access_token=xxxxxxxx

Given the above, here are my questions

I’ve placed my code in the Apps Code section and called my App “CrestronAPI”. Given that what should the url be so the call from the Crestron processor is routed to my groovy code?
I am not, at least until I get the basics working, using OAUTH. Do I need to include an access token as is done with the Maker call above? If so, how do I generate the access token? I saw it generated in the settings page of the Maker app.

Thanks in advance for the help

jbasen · March 21, 2020, 2:13am

Well, I've made some progress. I realized that the Apps code was just an editing area. I've now gone and installed my code as a User App and found its id is 36. So my call now looks like this

http://IPAddress/apps/api/36/switches

where switches should return a list of the switches on my hub. When I enter in my browser I just get back "nullinvalid_token"

Any ideas on what I'm doing wrong would be welcome.

Thanks in advance for the help

jeubanks · March 21, 2020, 2:38am

There's several ways to integrate with Hubitat.

Status Integration:

App/Driver that can send information however you want it to.
Native EventSocket/Websocket. This is not 'official' but it's widely used even with the native DashBoard so unless they make major breaking changes I think this is safe for now at least
HTTP Post of device events

Control Integration:
The Maker API app is the direct route to control devices for integration. This is a mostly complete API. This allow direct control of devices and their supported features with a simple HTTP call.

I use the EventSocket and Maker API in two of the integrations I've done and they work very well for me and others. The HomeSeer integration is used by many and works well. I'm no longer maintaining it so I'm not sure of it's current status. The ISY integration follows the same lines of the EventSocket and Maker API and several users from ISY use this and I still maintain it.

There's also a more recent Home Assistant component which many are using that seems very good and there's also a Node-RED integration which I want to look at and I've been following. I haven't used either of these two integration yet but I plan on toying with them soon.

bertabcd1234 · March 21, 2020, 2:45am

The access token is part of OAuth, so they're tied. But you also need to define "mappings" so your app knows what the parts of the URL means (the Maker API, apparently, mapped /devices to something in its code).

Fair warning: what you want to do is not super-easy if you are new to the platform. Hubitat's developer docs are a bit lacking (and to be fair, they bill themselves as open but not a development platform). The docs for SmartThings are pretty close in most regards, mostly including this, but besides URL differences for cloud, Hubitat also has local endpoints. This thread has a bit more specifically on this: Oauth Flow Cloud and Local

Here's a basic app that serves a simple HTML page (JSON would be even easier!) and gives you the link to do so from the app. It's not super-complete, and note that you have to fully install the app (click "Done" then go back in) before it will actually work, but hopefully it shows you the basics of how it can be done:

// Example OAuth app for Hubitat

definition (
    name: "Example OAuth App",
    namespace: "Example",
    author: "Author",
    description: "Example of local and cloud OAuth links/mappings",
    category: "Convenience",  
    iconUrl: "",
    iconX2Url: "",
    iconX3Url: ""
)

preferences {
    page(name: "myPage", uninstall: true, install: true) {
        section("Links") {
            paragraph("<a href=\"${getUrl('myFirstMapping')}\">Local LAN link to myFirstMapping</a>")
            paragraph("<a href=\"${getUrl('myFirstMapping', false)}\">Cloud chart link to myFirstMapping</a>")
        }
    }
}

def installed() {
    log.info("Installed with settings: ${settings}")
    initialize()
}

def uninstalled() {
    log.info("Uninstalling")
}

def updated() {
    log.info("Updated with settings: ${settings}")
    initialize()
}

def initialize() {
    log.debug("Initializing...")
    initEndpoint()
}

private initEndpoint() {	
	if (!state.accessToken) {
		try {
			def accessToken = createAccessToken()
			if (accessToken) {
                state.accessToken = accessToken
			}
		} 
		catch(e) {
			state.accessToken = null
		}
	}	
	return state.accessToken
}

private getUrl(path, local=true) {
	def url = (local ? "${getFullLocalApiServerUrl()}/$path?access_token=${state.accessToken}" : 
                       "${getFullApiServerUrl()}/$path?access_token=${state.accessToken}")
	return url
}

mappings {
	path("/myFirstMapping") {action: [GET: "myHTMLEndpoint"]}
}

def myHTMLEndpoint() {    
    render(contentType: "text/html", data: 
        """<html>
        <head>
          <title>My Page</title>
        </head>
        <body>
          <h1>My Page</h1>
          <p>My Text</p>
        </body>
        </html>"""
    )
}

EDIT: While I was writing this, I see you made more progress. My assumption above is that you are trying to write a custom app. If you are trying to integrate with something else, several built-in or existing community options can help (e.g., MakerAPI provides endpoints you can do a lot with) without you needing to write a custom app on the Hubitat side.

jbasen · March 21, 2020, 3:33am

Thanks. After a side conversation and some more research it looks like the maker app will do everything I need on the hubitat side. I'm just going to have to rewrite what I've done on the Crestron side of things; which won't be too hard.

Thanks again for your help

jf1 · April 8, 2020, 2:34pm

I'd like to use the code you develop to integrate with my Crestron system so I may have control over a few Osram Sylvania RGBW Zigbee lights (currently connected to Hubitat). Here are some of the functions/commands that would be useful to have exposed to the Crestron integration for RGBW LEDs:

"command":"configure","type":["n/a"]},
"command":"off","type":["n/a"]},
"command":"on","type":["n/a"]},
"command":"refresh","type":["n/a"]},
"command":"setColorTemperature","type":["NUMBER"]},
"command":"setHue","type":["NUMBER"]},
"command":"setLevel","type":["NUMBER","NUMBER"]},
"command":"setSaturation","type":["NUMBER"]},
"command":"startLevelChange","type":["ENUM"]}, up,down
"command":"stopLevelChange","type":["n/a"]}]

Also, in general the following functions would be great
Turn switches on/off
Hit virtual buttons
Select scenes

Thank you.

jbasen · April 8, 2020, 3:34pm

I've made quite a bit of progress but the code isn't ready for general release yet. However, I'm interested in someone else beta testing it. I'll send you a PM