# Pi-hole Binding

The Pi-hole Binding is a bridge between openHAB and Pi-hole, enabling users to integrate Pi-hole statistics and controls into their home automation setup. Pi-hole is a DNS-based ad blocker that can run on a variety of platforms, including Raspberry Pi.

Pi-hole is a powerful network-level advertisement and internet tracker blocking application. By intercepting DNS requests, it can prevent unwanted content from being displayed on devices connected to your network. The Pi-hole Binding allows you to monitor Pi-hole statistics and control its functionality directly from your openHAB setup.

# Features

Real-time Statistics: Monitor key metrics such as the number of domains being blocked, DNS queries made today, ads blocked today, and more.
Control: Enable or disable Pi-hole's blocking functionality, configure blocking options, and adjust privacy settings directly from openHAB.
Integration: Seamlessly integrate Pi-hole data and controls with other openHAB items and rules to create advanced automation scenarios.

# Supported Things

server: Pi-hole server

# Thing Configuration

# `server` Thing Configuration

Name	Type	Description	Default	Required	Advanced
hostname	text	Hostname or IP address of the device	N/A	yes	no
token	text	Token to access the device. To generate token go to `settings` > `API` > `Show API token`	N/A	yes	no
refreshInterval	integer	Interval the device is polled in sec.	600	no	yes

# Channels

Channel	Type	Read/Write	Description
domains-being-blocked	Number	RO	The total number of domains currently being blocked.
dns-queries-today	Number	RO	The count of DNS queries made today.
ads-blocked-today	Number	RO	The number of ads blocked today.
ads-percentage-today	Number	RO	The percentage of ads blocked today.
unique-domains	Number	RO	The count of unique domains queried.
queries-forwarded	Number	RO	The number of queries forwarded to an external DNS server.
queries-cached	Number	RO	The number of queries served from the cache.
clients-ever-seen	Number	RO	The total number of unique clients ever seen.
unique-clients	Number	RO	The current count of unique clients.
dns-queries-all-types	Number	RO	The total number of DNS queries of all types.
reply-unknown	Number	RO	DNS replies with an unknown status.
reply-nodata	Number	RO	DNS replies indicating no data.
reply-nxdomain	Number	RO	DNS replies indicating non-existent domain.
reply-cname	Number	RO	DNS replies with a CNAME record.
reply-ip	Number	RO	DNS replies with an IP address.
reply-domain	Number	RO	DNS replies with a domain name.
reply-rrname	Number	RO	DNS replies with a resource record name.
reply-servfail	Number	RO	DNS replies indicating a server failure.
reply-refused	Number	RO	DNS replies indicating refusal.
reply-notimp	Number	RO	DNS replies indicating not implemented.
reply-other	Number	RO	DNS replies with other statuses.
reply-dnssec	Number	RO	DNS replies with DNSSEC information.
reply-none	Number	RO	DNS replies with no data.
reply-blob	Number	RO	DNS replies with a BLOB (binary large object).
dns-queries-all-replies	Number	RO	The total number of DNS queries with all reply types.
privacy-level	Number	RO	The privacy level setting.
enabled	Switch	RO	The current status of blocking
disable-enable	String	RW	Is blocking enabled/disabled

# Full Example

# Thing Configuration

Thing pihole:server:a4a077edb8 "Pi-hole" @ "Location"
[
    refreshIntervalSeconds=600,
    hostname="http://123.456.7.89",
    token="as654gadf3h1dsfh654dfh6fh7et654asd3g21fh654eth8t4swd4g3s1g65sfg5"
] {
    Channels:
        Type number : domains_being_blocked "Domains Blocked" [ ]
        Type number : dns_queries_today "DNS Queries Today" [ ]
        Type number : ads_blocked_today "Ads Blocked Today" [ ]
        Type number : ads_percentage_today "Ads Percentage Today" [ ]
        Type number : unique_domains "Unique Domains" [ ]
        Type number : queries_forwarded "Queries Forwarded" [ ]
        Type number : queries_cached "Queries Cached" [ ]
        Type number : clients_ever_seen "Clients Ever Seen" [ ]
        Type number : unique_clients "Unique Clients" [ ]
        Type number : dns_queries_all_types "DNS Queries (All Types)" [ ]
        Type number : reply_UNKNOWN "Reply UNKNOWN" [ ]
        Type number : reply_NODATA "Reply NODATA" [ ]
        Type number : reply_NXDOMAIN "Reply NXDOMAIN" [ ]
        Type number : reply_CNAME "Reply CNAME" [ ]
        Type number : reply_IP "Reply IP" [ ]
        Type number : reply_DOMAIN "Reply DOMAIN" [ ]
        Type number : reply_RRNAME "Reply RRNAME" [ ]
        Type number : reply_SERVFAIL "Reply SERVFAIL" [ ]
        Type number : reply_REFUSED "Reply REFUSED" [ ]
        Type number : reply_NOTIMP "Reply NOTIMP" [ ]
        Type number : reply_OTHER "Reply OTHER" [ ]
        Type number : reply_DNSSEC "Reply DNSSEC" [ ]
        Type number : reply_NONE "Reply NONE" [ ]
        Type number : reply_BLOB "Reply BLOB" [ ]
        Type number : dns_queries_all_replies "DNS Queries (All Replies)" [ ]
        Type number : privacy_level "Privacy Level" [ ]
        Type switch : enabled "Status" [ ]
        Type string : disable-enable "Disable Blocking" [ ]
}

# Item Configuration

Number domains_being_blocked "Domains Blocked" { channel="pihole:server:a4a077edb8:domains_being_blocked" }
Number dns_queries_today "DNS Queries Today" { channel="pihole:server:a4a077edb8:dns_queries_today" }
Number ads_blocked_today "Ads Blocked Today" { channel="pihole:server:a4a077edb8:ads_blocked_today" }
Number ads_percentage_today "Ads Percentage Today" { channel="pihole:server:a4a077edb8:ads_percentage_today" }
Number unique_domains "Unique Domains" { channel="pihole:server:a4a077edb8:unique_domains" }
Number queries_forwarded "Queries Forwarded" { channel="pihole:server:a4a077edb8:queries_forwarded" }
Number queries_cached "Queries Cached" { channel="pihole:server:a4a077edb8:queries_cached" }
Number clients_ever_seen "Clients Ever Seen" { channel="pihole:server:a4a077edb8:clients_ever_seen" }
Number unique_clients "Unique Clients" { channel="pihole:server:a4a077edb8:unique_clients" }
Number dns_queries_all_types "DNS Queries (All Types)" { channel="pihole:server:a4a077edb8:dns_queries_all_types" }
Number reply_UNKNOWN "Reply UNKNOWN" { channel="pihole:server:a4a077edb8:reply_UNKNOWN" }
Number reply_NODATA "Reply NODATA" { channel="pihole:server:a4a077edb8:reply_NODATA" }
Number reply_NXDOMAIN "Reply NXDOMAIN" { channel="pihole:server:a4a077edb8:reply_NXDOMAIN" }
Number reply_CNAME "Reply CNAME" { channel="pihole:server:a4a077edb8:reply_CNAME" }
Number reply_IP "Reply IP" { channel="pihole:server:a4a077edb8:reply_IP" }
Number reply_DOMAIN "Reply DOMAIN" { channel="pihole:server:a4a077edb8:reply_DOMAIN" }
Number reply_RRNAME "Reply RRNAME" { channel="pihole:server:a4a077edb8:reply_RRNAME" }
Number reply_SERVFAIL "Reply SERVFAIL" { channel="pihole:server:a4a077edb8:reply_SERVFAIL" }
Number reply_REFUSED "Reply REFUSED" { channel="pihole:server:a4a077edb8:reply_REFUSED" }
Number reply_NOTIMP "Reply NOTIMP" { channel="pihole:server:a4a077edb8:reply_NOTIMP" }
Number reply_OTHER "Reply OTHER" { channel="pihole:server:a4a077edb8:reply_OTHER" }
Number reply_DNSSEC "Reply DNSSEC" { channel="pihole:server:a4a077edb8:reply_DNSSEC" }
Number reply_NONE "Reply NONE" { channel="pihole:server:a4a077edb8:reply_NONE" }
Number reply_BLOB "Reply BLOB" { channel="pihole:server:a4a077edb8:reply_BLOB" }
Number dns_queries_all_replies "DNS Queries (All Replies)" { channel="pihole:server:a4a077edb8:dns_queries_all_replies" }
Number privacy_level "Privacy Level" { channel="pihole:server:a4a077edb8:privacy_level" }
Switch enabled "Status" { channel="pihole:server:a4a077edb8:enabled" }
String disable_enable "Disable Blocking" { channel="pihole:server:a4a077edb8:disable-enable" }

# Actions

Pi-hole binding provides actions to use in rules:

import java.util.concurrent.TimeUnit
        
rule "test"
when
    /* when */
then
	val actions = getActions("pihole", "pihole:server:as8af03m38")
	if (actions !== null) {
            // disable blocking for 5 * 60 seconds (5 minutes)
            actions.disableBlocking(5 * 60)
    
            // disable blocking for 5 minutes
            actions.disableBlocking(5, TimeUnit.MINUTES)
    
            // disable blocking for infinity
            actions.disableBlocking(0)
            actions.disableBlocking()
    
            // enable blocking
            actions.enableBlocking()
	} 
end

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)

← Philips Somneo pilight →

# Pi-hole Binding

# Features

# Supported Things

# Thing Configuration

# server Thing Configuration

# Channels

# Full Example

# Thing Configuration

# Item Configuration

# Actions

# `server` Thing Configuration