OH3: Integrate PI-Hole via HTTP-Binding using the UI

Tutorials & Examples
, ,
1

OH3: Integrate PI-Hole via HTTP-Binding (updated to reflect @justinwilczek improvement)

Prerequisites:

HTTP-Binding installed (Settings → Add-ons → Bindings)
JSONPath-Transformation installed (Settings → Add-ons → Transformations)

Implementation:

1. Create a new HTTP-Thing manually (Settings → Things)

image
image1278×603 20 KB

image
image1276×368 19 KB

2. Create a new HTTP URL Thing

Set the Label of your Thing to something meaningful

image
image942×480 14.6 KB

Set your Base URL (replace with the IP-Adress of your PI-Hole Instance)
image

Click on show advanced to be able to set Content Type to ‚application/json‘

image
image856×144 3.4 KB

image
image857×242 4.25 KB

and the click on ‚Create Thing‘
image

Now the new Thing should be in the Thing-List

image
image1277×510 39 KB

If you click on it, you get the Thing-Details

image
image2262×903 74.9 KB

And on the second TAB the assigned Channels (which is empty until now)

image
image966×448 8 KB

Now you can add your channels one by one

for example: Domains being blocked

image
image938×1072 26.4 KB

And to make the result visible you finally have to link an Item to this Channel

image
image841×1245 31.6 KB

And as a result you have now a PI-Hole Thing with Channel and linked Item

You can use my Thing-Code as a reference for your own Thing

Things Code 
UID: http:url:000e4c241a
label: pihole
thingTypeUID: http:url
configuration:
  authMode: BASIC
  ignoreSSLErrors: false
  baseURL: http://<YOUR-PIHOLE-IP/admin/api.php
  refresh: 30
  commandMethod: GET
  contentType: application/json
  timeout: 3000
channels:
  - id: domains_being_blocked
    channelTypeUID: http:number
    label: Domains being blocked
    description: null
    configuration:
      stateTransformation: JSONPATH:$.domains_being_blocked
  - id: dns_queries_today
    channelTypeUID: http:number
    label: DNS Queries today
    description: null
    configuration:
      stateTransformation: JSONPATH:$.dns_queries_today
  - id: ads_blocked_today
    channelTypeUID: http:number
    label: Ads blocked today
    description: null
    configuration:
      stateTransformation: JSONPATH:$.ads_blocked_today
  - id: ads_percentage_today
    channelTypeUID: http:number
    label: Ads percentage today
    description: null
    configuration:
      stateTransformation: JSONPATH:$.ads_percentage_today
  - id: unique_domains
    channelTypeUID: http:number
    label: Unique Domains
    description: null
    configuration:
      stateTransformation: JSONPATH:$.unique_domains
  - id: queries_forwarded
    channelTypeUID: http:number
    label: Queries forwarded
    description: null
    configuration:
      stateTransformation: JSONPATH:$.queries_forwarded
  - id: queries_cached
    channelTypeUID: http:number
    label: Queries cached
    description: null
    configuration:
      stateTransformation: JSONPATH:$.queries_cached
  - id: clients_ever_seen
    channelTypeUID: http:number
    label: Clients ever seen
    description: null
    configuration:
      stateTransformation: JSONPATH:$.clients_ever_seen
  - id: unique_clients
    channelTypeUID: http:number
    label: Unique Clients
    description: null
    configuration:
      stateTransformation: JSONPATH:$.unique_clients
  - id: Status
    channelTypeUID: http:string
    label: Status
    description: ""
    configuration:
      stateTransformation: JSONPATH:$.status
2 Likes
2

Just curious if there is a specific reason not to use the State Transformation property on the HTTP thing channels to do the JSONPATH transformation instead of doing the transformation with the profile? And use number channels.

  - id: ads_blocked_today
    channelTypeUID: http:number
    label: Ads blocked today
    description: ""
    configuration:
      stateTransformation: JSONPATH:$.ads_blocked_today
3

you are correct. This is a ceaner way to solve this. And everything would be in the Code-Tab afterwards.
I think I will adopt this and update the Tutorial.

4

Updated OP with JSONPATH-Transformation at the Thing-Level

5

@Christian_Brosius have you also linked the enable/disable button? How have you done it?

6

You can send enable/disable commands through the API also.

Both of them require the API token that you can get from the API/Web interface page in the pi-hole settings. Or from the /et/pihole/setupVars.conf (the WEBPASSWORD entry in that file).

To disable: http://<piholeip>/admin/api.php?disable=<seconds>&auth=<WEBPASSWORD>
To enable: http://<piholeip>/admin/api.php?enable&auth=<WEBPASSWORD>

I think the only way to implement this is by adding two channels; one each for disable and enable.

On my instance; I have added a Number channel for disable.

In the advanced options on the channel…
image
To disable, you send a command to the linked item and it’ll stick the number into the URL and the pi-hole will get disabled for that long. A value of 0 will disable it indefinitely.

I have not hooked up anything for specific enable commands; have not figured out the best way to handle it. It could be a Switch channel, with the Command URL Extension set to ?enable&auth=<WEBPASSWORD>. This would send the enable command for both ON and OFF states; so I haven’t bothered yet.

7

This topic was automatically closed 41 days after the last reply. New replies are no longer allowed.

9

Hi all,

It may be interesting for you to check, if there are any updates available for your Pi-Hole.
I do not regularly check the Pi-Hole Dashboard myself and was looking for a way to get notified if i need to update my instance.

image

Fortunately the api provides a versions endpoint. http://<piholeip>/admin/api.php?versions

You can check if updates are available with a boolean api response and also get the current installed und latest available versions, if you want to display them.

image

Here is my extension to the basic thing config described in this thread.
It still uses http://<piholeip>/admin/api.php as base endpoint in the http binding and just extends the ?versions in the needed channel configurations.

- id: core_update_available
    channelTypeUID: http:string
    label: Core Update Available
    description: ""
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.core_update
  - id: core_current_version
    channelTypeUID: http:string
    label: Current Core Version
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.core_current
  - id: core_latest_version
    channelTypeUID: http:string
    label: Latest Core Version
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.core_latest
  - id: web_update_available
    channelTypeUID: http:string
    label: Web Update Available
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.web_update
  - id: web_current_version
    channelTypeUID: http:string
    label: Current Web Version
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.web_current
  - id: web_latest_version
    channelTypeUID: http:string
    label: Latest Web Version
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.web_latest
  - id: ftl_update_available
    channelTypeUID: http:string
    label: FTL Update Available
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.FTL_update
  - id: ftl_current_version
    channelTypeUID: http:string
    label: Current FTL Version
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.FTL_current
  - id: ftl_latest_version
    channelTypeUID: http:string
    label: Latest FTL Version
    description: null
    configuration:
      mode: READONLY
      stateExtension: ?versions
      stateTransformation: JSONPATH:$.FTL_latest

Full api response example with the complete available JSON:

{
  "core_update":true,
  "web_update":true,
  "FTL_update":true,
  "core_current":"v5.11.4",
  "web_current":"v5.13",
  "FTL_current":"v5.16.3",
  "core_latest":"v5.12",
  "web_latest":"v5.14.2",
  "FTL_latest":"v5.17",
  "core_branch":"master",
  "web_branch":"master",
  "FTL_branch":"master"
}

EDIT:

Of course you can configure the update available channels as switch for using it in your rules.
I just used string for demonstration purposes here. :slight_smile:

- id: ftl_update_switch
    channelTypeUID: http:switch
    label: FTL Update Available Switch
    description: ""
    configuration:
      onValue: "true"
      mode: READONLY
      stateExtension: ?versions
      offValue: "false"
      stateTransformation: JSONPATH:$.FTL_update
4 Likes
10

Wonderful directions. It works without Pi-Hole Password. Can i get it work with Password Integration?

11

As mentioned above you can get an auth token from your Pi-hole:

image
image1170×1973 175 KB

use the token in the command url like below:
/admin/api.php?%2$s&auth=TOKEN_GOES_HERE

12

This is a good idea, but it doesen’t works. what should %2$s do?

13

You may have just a look into the binding documentation? :wink:

14

Oh I just pasted the whole thing from my config to show you how it could look like with the auth part in the url. You don’t have to use the %2$ variable, it is in no way related to authentication.

As BratHuhn pointed out this is already well documented in the binding documentation so I would also recommend to read this first and come back with remaining questions later.