openhab-addons/bundles/org.openhab.binding.pihole/README.md

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	URL (hostname or IP address) of the pihole web server	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
serverVersion	text	Defines the API to be used with this server	v5	no	no

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
gravity-last-update	DateTime	RO	Last update of gravity
gravity-file-exists	DateTime	RO	Does gravity file exists

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