- Set up Maker API on
hubitat.local
or useDEFAULT_HUB_IP
environment varialbe to specify the IP of your primary hub. - Configure mandatory environment variables:
MAKER_API_APP_ID
,MAKER_API_TOKEN
,BOT_TOKEN
.- If you know the ID of your DM chat with your bot, you can add it as
CHAT_ID
variable. - If your primary hub is not using
hubitat.local
DNS entry, useDEFAULT_HUB_IP
to specify the ip.
- If you know the ID of your DM chat with your bot, you can add it as
- Deploy the Docker container.
- Start sending commands to your bot!
/on [device to turn on]
- Turns on a specified device.- Example:
/on Kitchen Lights
- Example:
/off [device to turn off]
- Turns off a specified device.- Example:
/off Porch Light
- Example:
/open [device to open]
- Opens a specified device (e.g., shades).- Example:
/open Loft Shades
- Example:
/close [device to close]
- Closes a specified device.- Example:
/close Loft Shades
- Example:
/cancel_alerts
- Cancels all alerts in HSM./update
- Updates all hubs for which Hub Information Drivers are exposed in the Maker API ofhubitat.local
./reboot [Hub Information Driver v3 instance name to reboot]
- Reboots a specified hub./refresh
- Refresh Devices from Hub/list
- Lists all Devices and their aliases.
You can refer to devices in several ways:
- Full name: Use the complete device name.
- Example:
/on Kitchen Lights
- Example:
- Short name: Omit
Lights
orLight
if they are the last word in the name.- Example:
/off Kitchen
- Example:
- Abbreviation: Use the first letters of each word in the full name.
- Example:
/on kl
- Abbreviation conflicts can be resolved by specifying the first non-conflicting letter in the first non-conflicting word of the name:
- Let's assume you have three conflicting devices,
Main Bedroom Lights
,Main Backyard Lights
, andMain Bathroom Lights
. All three are abbreviated tombl
, which creates a conflict. - Use
mbel
forMain Bedroom Lights
ase
in the second word (Bedroom) is the first unique letter, distinguishing it fromMain Backyard Lights
andMain Bathroom Lights
. - Use
mbacl
forMain Backyard Lights
asc
in the second word (Backyard) is the first unique letter, distinguishing it fromMain Bathroom Lights
. Usingmbal
won't be enough, as it is still the same for bothMain Bathroom Lights
andMain Backyard Lights
. - Correspondingly,
Main Bathroom Lights
is uniquely abbreviated tombatl
, notmbal
.
- Let's assume you have three conflicting devices,
- Example:
- For hubs updates: Hubitat version 2.3.9.175 or higher.
- Install the Maker API app on the
hubitat.local
hub. - Ensure Maker API control of HSM is allowed for
/cancel_alerts
. - Expose all needed devices in Maker API (including devices from other hubs via mesh).
- Ensure Hub Information Driver v3 is installed on every hub (via Hubitat Package Manager) and exposed in Maker API on
hubitat.local
(directly and via mesh). - Create a bot in Telegram using BotFather bot.
- Add the commands using
setcommands
in BotFather. - Configure environment variables:
- Mandatory:
MAKER_API_APP_ID
- The Maker API app ID.MAKER_API_TOKEN
- The Maker API token.BOT_TOKEN
- The Telegram bot token.
- Optional:
CHAT_ID
- The ID of your DM chat with the Bot (or other chat the bot is added to). If you use that variable, the bot will be able to proactively send information to the chat. If you don't use it, it will only reply to your messages. There are number of ways to find this ID, some of them are listed here.DEFAULT_HUB_IP
– The IP of the hub the Maker API app is installed on. Defaults to DNS hostname ofhubitat.local
.
- Mandatory:
- Deploy the Docker image:
- Load the Docker image:
docker load < tg-hubitat-bot-docker-image.tar
- Create and run the container:
docker run -d --name tg-hubitat-bot -e MAKER_API_APP_ID -e MAKER_API_TOKEN -e BOT_TOKEN tg-hubitat-bot
It's almost certain that you'll need to add new device types to the JSON hierarchy to support your devices.
Device.tk contains the list of supported devices in the form of classes with their abilities.
As currently, only actuators and shades are supported, so all the concrete device implementations extend from either jbaru.ch.telegram.hubitat.model.Device.Actuator
or jbaru.ch.telegram.hubitat.model.Device.Shade
(except jbaru.ch.telegram.hubitat.model.Device.Hub
).
Add another class that extends from the relevant abstract class (to provide support for the correct commands) and enter the device type from Hubitat in the @SerialName
annotation. Done.
./gradlew build
- Build the project../gradlew jibDockerBuild
- Build a Docker container../gradlew jibBuildTar
- Create a portable tar of the container.