Mac Home Automation

Without a “cloud” our siri integration was limited to asking her to turn things on and off that were shared to homekit via the Home Kit plugin. The iOS Short Cut app extended this a lot by letting you assign phrases to trigged the turning on and off of home kit devices. So instead of saying “Siri, turn off kitchen light group” you could instead say something like “Siri we’re finished in the kitchen, please turn out the lights”

This was fun but lacked the ability to get her to say anything useful to you. In this example I’ll show how to use the HTML/JSON server in XTension to get Siri to tell you if any doors have been left unlocked by asking her “Siri, tell me about the house” but of course you can use any phrase that makes sense to you and you can create as many of these as you like.

The shortcuts app added at some point a “scripting” action that has a lot of potentially useful actions, Scripting is a bit of a misnomer as it implies that you’re writing code but what you’re really doing is selecting actions from a popup and then configuring them. As someone who writes code I think this is actually harder than just a few lines of AppleScript, but evidently apple disagrees…

If you don’t already have an instance of the HTML/JSON Plugin running please head to the wiki page for that and set one up. Create a specific “tag” for this. This doesn’t need to be complicated or long as it is not a password and does not provide any real security it is just a way to use a single instance of the server and while developing if you break something you can disable one project or connection without having to turn off the whole thing. You will also need to enter this into the settings in the shortcut app so dont make anything too difficult to type or too long. Choose a reasonable high port for the server to run on. This is covered in the HTML/JSON server plugin article but for this example I’m going to use the port of “40621” for no reason other than I just picked that. The port needs to be higher than 1024 and less than 65k and probably shouldn’t be one of the other “well known” ones so use one with an extra digit than just 1025 for example.

If you wish to be able to use these shortcuts outside the house you also need to setup a passthrough and be able to get to it via a dyndns address. For something like this it is better to use the ngrok setup in XTension to create a real encrypted pipe to a site with a real https certificate on the other side.

It may also be that there is a way to make sure that Home Kit does the request from the home kit host inside your network, the apple TV or other device that handles the rest of the local work but it does not look like this is the case to me obviously. More experimentation might make this all unnecessary. Never the less it is a good thing to have an ngrok account and use it for remote access to your web interfaces.

Now you need a Unit assigned to the HTML server that we can catch the hit from siri. Create a New Unit and select the HTML JSON Server instance you created in the step above from the “Interface” popup. The only device selection possible is “Register”

The Name you give the Unit is not important to the coding, so use a descriptive name so you can more easily know what it does when you are looking for it a year from now.

The Address is important. This will be used in the settings on your iPhone to reach this specific Unit. It is not used in what you say to Siri or what she says back so it’s not important except that you have to type it on the phone and that it be unique inside of XTension. For this example I’m calling it “HOUSECHECKUP“

When Siri makes the call for this data the request will be sent to this Unit’s ON script. Anything you return from there will be spoken by Siri. For the moment lets just make the script return a simple test phrase so make sure everything else is working and then we will add the complex scripting to build a more useful reply at the end.

Click the Edit button for the On Script and create the handler for the web request. You would normally use the “Insert” button to insert the default handler to work in but the HTML plugin pre-dates my adding of that feature so it doesn’t work here. Add the following to the On script:

on JSONRequest( formData, JSONData)
    
    write log “We received the request from Siri"

    send reply “It appears that it is all working so far!” return code 200 content type “text/plain"

end JSONRequest

Save the script and save the Unit. Make sure you have enabled the HTML/JSON Server plugin instance you created. If you wish to test it you can hit the server in a browser to see if it returns the text. Enter the following into the browser:

http://address.of.xtension.machine:40621/TheTokenYouCreated/HOUSECHECKUP/

Replacing the address, port, token and unit address with the values you used in the earlier steps. You should see the plain text of the string we returned from the script.

On your iPhone open the ShortCuts all and press the “+” button at the upper right to create a new shortcut. You’ll get a window something like this one. Under the search field are some selections in blue to choose from. You’ll need to scroll that over to the right until you find the “Web” actions. Tap that to get the list of web actions.

Scroll down to the section with the header “Web Requests” and select the list item “Get Contents of URL”

The resulting entry will look something like the image to the right. Tap the blue “URL” to enter the url. It will be the same as you entered into the browser to test it. Click the “Done” in the list of buttons right above the keyboard, not the Done at the top of the screen or it will think you’re finished creating your shortcut.

Now we add another step. Pull up the list of actions under the “Search Actions” field. Tap the first one called “Scripting” and scroll down until you get to the section labeled “Audio” from that list select the item called “Speak Text”. It should look something the the next screen shot but the URL will be yours instead of my “whatever”…

Now we just need to rename the shortcut and what name you give it is the phrase you need to say to Siri to get her to do this. Tap the title at the top of the screen which has a little down pointing arrow in a circle next to it indicating it has a popup menu to display if you tap it. The default is the name of the first action so right now it probably says “Get Contents of URL”. Select “Rename” from the popup menu and change it to something that makes sense to you, for this example I’m calling mine “Tell me about the house”

Save the shortcut and tell your phone “Siri (or Hey Siri if you dont have her set to just listen for her name) Tell me about the house.”

It will take her a moment to think about it and then she should say what we returned from the Unit script. Thats pretty cool and you can imagine all sorts of uses for this can’t you!

Here is an example script that will walk all your door sensors and read out to you if any of them are open. You can expand the script the way it is by adding more units to the list or make deeper changes if you wish to send more information or dont like how I put it together.

The list of “DoorsToCheck” is a List of Lists. Each list entry has 2 items, the name of the Unit in XTension for looking up it’s status and then a second item which is the friendly name, or the way you want to phrase it when she is reading to you. For example if the unit name is “Perimeter South Garage Door” you might not want her to read that out, you might prefer that she say “Sarah’s Garage Door” and so forth. So every entry must have 2 things in it as shown. Be careful with the syntax and the brackets if you haven’t used that a lot in AppleScript. It cab get a little confusing. I think adding the line continuation characters which look like sideways L’s makes the list more readable, but it does make the code a little harder to type. If you haven’t used those before you get them by holding the option key and typing the letter L.

There is more discussion as comments in the code below. You can copy and paste into the House Checkup Unit we created in the steps above to replace the testing code that just returned a single phrase.

property doorsToCheck : {¬
	{“East Garage Door", “Sarahs Garage"}, ¬
	{“West Garage Door", "Jamies Garage"}, ¬
	{“DOOR Utility Porch", "The Utility Porch"}, ¬
	{“DOOR garage", "The door to the garage"}, ¬
	{“DOOR Master Deck", "The Master Bedroom Deck"}, ¬
	{“DOOR front door", "The Front Door"}, ¬
	{“DOOR Kitchen Door", "The Kitchen Patio"}, ¬
	{“DOOR Screened In Porch", "The Doors to the Screened in porch”}}



on JSONRequest(formData, JSONData)
	set doorsOpen to {}
	
	(* walk the list of doors and build a list of any open doors *) 
	repeat with doorRecord in doorsToCheck
		set unitName to item 1 of doorRecord -- the actual unit name in XTension
		set friendlyName to item 2 of doorRecord -- The more friendly name for Siri to speak
		
		(* if the Unit is on, then the door is open, add it to the list *)
		if (status of unitName) then copy friendlyName to the end of doorsOpen
		
	end repeat
	
	set doorOpenCount to count of doorsOpen
	
	if doorOpenCount is 0 then
		set reply to "All Doors Are Closed”

	else if doorOpenCount = 1 then
		set reply to item 1 of doorsOpen & " is open. “

	else

		(* if more than one door is open, first say the number of doors that are open
			and then read them all out *)

		set reply to doorOpenCount & " doors are open, "
		
		repeat with i from 1 to doorOpenCount

			(* I wanted this as a comma separated list of names but
				to sound more like normal speech if it is the last
				door in the list I add the word “and” *)

			if i = doorOpenCount then
				set reply to reply & " and "
			else
				set reply to reply & ", "
			end if


			(* This line should just append the friendly name to the reply string. 
				In my own system for some reason this created a list of text items
				rather than just extending the single reply text. When I returned a single
				string it put these together without any spaces which was not correct.
				Using this slightly strange syntax fixed the problem *)

			set reply to reply & " " & (item i of doorsOpen) as text

		end repeat
		
		(* Add a period at the end again for more natural speech *)
		set reply to reply & ". "
		
		
	end if


	(* Finally send the reply with the Send Reply verb and also write it to the log for easier debugging in case
		it doesnt say exactly what you want it is easier to see what it is really doing *)

	
	write log reply

	send reply reply return code 200 content type “text/plain"

end JSONRequest

Save that and run your shortcut! You can also run it from the shortcut app by just tapping the shortcut in the list so if you need to make changes or fixes to it it’s a little bit faster to do it from there.

You can add more items to check. Perhaps a list of door locks you can get the status to so that Siri can re-assure you that “All Doors Are Locked” or “You left the Front Door Unlocked again”

Mine also reminds me to setup the coffee for tomorrow morning :)

This is just an example, you can create as many of these as you wish and the possibilities are very interesting!

–James 2/3/2025