GHBot

An IRC bot

• Design by r3boot
  • https://github.com/r3boot/jaken => note: since the original design some enhancements have been done

• Implemented by Folkert
  • github: https://github.com/folkertvanheusden/GHbot

• • code examples for plugins:
    • Python: https://github.com/NURDspace/nurdspace-ircbot-plugin-python-example
    • Arduino (on ESP8266/ESP32): https://github.com/NURDspace/nurdspace-ircbot-plugin-esp8266-example
    • Home Assistant integration (in Python): https://github.com/NURDspace/ghbot-hass

design (in short; see Jaken (r3boot) for full)

GHBot listens on a few MQTT topics. Plugins can send commands to GHBot via those.

• topic: GHBot/to/bot/register
  • value: cmd=...|descr=...|agrp=...|athr=...|loc=...
    • cmd=... defines (one of) the command(s) this plugin listens to (required)
    • descr=... short description of what the cmd does. this is returned by "!help cmd" (required)
    • agrp=... ACL group required for this command (optional, default is access for everyone)
    • athr=... author (optional)
    • loc=... where it lives (optional), for when e.g. the plugin is running on an arduino somewhere hidden
  • you should send this every 5 seconds or a command will disappear automatically

• topic: GHBot/to/irc/channel/privmsg
  • value: text to publish to channel - note that the '#' in the channel name must be omitted

• topic: GHBot/to/irc-person/nick
  • value: text to send to the person nick in a PM

GHBot also sends everything it receives via IRC to MQTT topics, for the plugins to be processed.

• topic: GHBot/from/bot/command
  • value: register - asks all plugins to immediately register all the commands it knows (see above)

• topic: GHBot/from/bot/parameter/prefix
  • value: command-prefix (e.g. '!' or '#' etc) this command asks plugins to respond to commands prefixed by this prefix.

• topic: GHBot/from/irc/ - please see r3boot's documentation

user management

• add a user:
  • addacl user nick group groupname
    • nick is the nickname of the user, ghbot will lookup the full name etc of the user by itself
    • group is currently either members or sysops but you can create new groups easily (by either defining them in a plugin or using addacl group, see below)

• create a new group:
  • addadcl group groupname cmd command
    • groupname is the new group, command is the (existing) command that you want to put in the new group

• delete a group:
  • delacl

• get a list of groups a user is in:
  • listacls nick

• connect a nick to a new hostname:
  • meet nick

• create an alias for a nick (...the hostname of a nick):
  • merge newnick oldnick

local(!) plugins (non-mqtt)

• listlp - list the available plugins
• showlp x - list the commands in plugin 'x'
• loadlp - load any new plugins (without restarting ghbot)
• reloadlp - reload an already loaded plugin

aliasses / defines

• aliasses are for commands, defines are "new commands"

• • alias new_command_name old_command_name
    • returns a number with which you can delete the alias

• • define new_command_name command definition
    • escapes:
      • %q command parameter
      • %u user invoking the command
      • %m like '/me'
      • %n post as a notice
    • returns a number with which you can delete the alias

• • deldefine number
    • delete an alias or define

TO DO

priority: ghbot priority

• !allot
• !badum - for terrible jokes
• !bclabel - Prints Bookcrossing labels @ Labelprinter @ SlabPi
• !label - Prints labels with free text @ Labelprinter @ SlabPi
• !janee - response in the affirmative or negatory sense to inquiries
• !events - show upcoming nurdspace events
• !learn
• !mpdtube - Sends search query or url to MPDTube
• !ot - shows OpenTherm data from Home assistant
• !ot-set - Updates OpenTherm thermostat setpoint through Home assistant
• !sensors - Queries sensors from Home assistant
• !speak / !spreek / !dire / !sprech / !habla - Text to speach using espeak on SlabPiSpacesound (different languages yay \o/) (Deligated to Melan)
• !statustoggle - (temp) manually switch the space from closed to open
• !sth - temps and humidities of the different rooms
• !ticker sends text to Led ticker
• !toggle - toggles switches (Sonoff, epc, pdu) through Home assistant
• !toggle-list - shows a list of IDs that !toggle can use
• !wau-temp - Read the external temperature from the WUR sensors
• !wikipedia - customised from the basic version
• !who - Checks which known devices are connected to the Wifi (if you want to be on here, see Jarvis#Enable_tracking_for_your_MAC_address)
• !wol - Performs wake-on-lan actions for machines in the space
• !power - Current power consumption
• !sensor - Read sensors from hass
• topic
• join to multiple channels
• configurable via configuration file
• !qs !quote-search
• !regen !sun !moon (met die laatste twee ook 'volgende X (volle maan/zonsopgang/zonsondergang) ' en 'huidige X (maanstand, zon elivatie (is al?) en, vorige x (volle maan/zonsopgang/ondergang)
• Make internal states accessible over mqtt (Plugins plugins loaded) -- see next item:
• Have plugins being able to report author and location for easier keeping track (Melan: My idea is to make a plugin that can make a page that can output all commands + help etc to a markdown on request) -- finished altough the layout may be pimped a bit
• !seen
• remove the silly http-implementation and/or add an http-api that allows to retrieve the plugin-state as a json-blob
  • also post-to-channel api

Feature Requests

• !merge new-nick old-nick
• buZz Make alias legible (like !moon 62 is aliased to .... !nowaytoknownow)
  • !viewalias
• buZz Autodescribing help for plugins
• buZz give !at a offset , so '!at +5 oven!' works to set a timer in 5 minutes , maybe +1h for 1 hour (its never seconds)
• buZz add highlight of nickname to reminder notification now does so!
• buZz give a error msg on unknown -anything- in PM , instead of silence (like on channel)
• buZz allow a group be a group member for ACL , so we can make a 'SD' group, and make 'members' a member of it
• buZz add !np -v or something else that can show the album of the current playing song

• r3boot Overzicht van plugins die herschreven moeten worden naar de nieuwe plugin structuur
  • zie hierboven

• r3boot RSS feeds beperken tot nurdspace resources, of verplaatsen naar #nurds-feeds kanaal oid
  • feeds verwijderd :-)

• r3boot Plugin output prefixen met de naam v/d plugin zodat filtering voorspelbaar word.
  • dit is iets wat de plugin zelf moet doen omdat de bot niet ziet wie de afzender is (die info zit niet in mqtt)

• r3boot Overzicht van operaties die beheerders kunnen uitvoeren op de bot (ops documentatie)
• The_Niz Partkeepr search
  • done
• The_Niz !btc in Eu ipv die nare dollah units
  • ik heb geen conversie dingetje naar euro, suggesties welkom though
• iets met dat je kunt configureren of iets een PRIVMSG of dat het een NOTICE is - hoewel kan een plugin dat niet al?
  • to/irc/(channel)/notice
• zarya please make !koffie <nick> give koffie to that nick and not the one typing !koffie unless no parm is given
  • gedaan
• The_Niz !@ voor (youtube) URL titel spam
  • gedaan
• r3boot Apply acceptable regex to incoming karma requests (eg: ^[a-zA-Z0-9_-]+{\+\+,--}$. This will prevent multikarma and calling the plugin multiple times.
  • karma.py has been severly dumbed down and no longer performs multikarma etc.
• The_Niz Keep track of commands that were once available in order to create an errormsg when the plugin is down
  • implemented in 5db0f18ca20b3471b3a71686f949822434e64647
• !message (zie kiki: !boodschap)
  • added
• stock quotes, see https://github.com/jlyheden/stockbot
• !karma-whyup !karma-whoup !karma-whodown !karma-whydown !karma-top10 !karma-bottom10 !karma-stats
  • implemented as !whykarma
• !op / auto-op
  • done

nurdspace specific

• Runs on container named harkbot

• hass plugin: https://github.com/nurdspace/ghbot-hass

• the following services exist that need to be restarted after a change to the specific plugin (or just kill -9 them as systemd will restart them)
  • udp-listener.service
    • hass messages
  • topic.service
    • irc topic
  • semwikievents.service
    • events added to the nurdspace wiki (!events)
  • erratic.service
    • stats of the server
  • seen.service
    • !seen <user>
  • geiger.service
    • geigercounter statistics
  • zorgverzekering.service
    • zorgverzekering / test / quit / choose / secondopinion / spacehex / wau-temp / allot / rijnstreek / janee / regen / !@
  • wacalc.service
    • wolfram alpha
  • net-tools.service
    • br0ken
  • minecraft.service
    • see Minecraft
  • learn.service
    • word?
  • label.service
    • label printer
  • message.service
    • send messages to (offline) users
  • karma.service
  • at.service
    • schedule messages
  • quotes.service
  • mpd-plugin.service
    • music services
  • deurbel.service / deurbel-to-sqlite3.service
    • doorbell notification
  • rss.service
    • checks for wiki changes, executes !speld
  • btc.service
    • bitcoin status
  • mp-service.service / mp.service
    • !mp / !mpstats / !mpdtoday
  • wanneer.service
    • predictor
  • GHBot.service
    • the main irc-bot itself
  • hass-ghbot.service
    • hass-services: !sth / !octoprint / !ot / !ot-set / !sensor / !sun / !power / !toggle / !toggle-list / !who / !mpdtube / !ticker
  • regex.service
    • s/bla/bli/
  • partkeepr.service
    • search in the nurdspace partkeepr database
  • nlenergie
    • show stofradar.nl energie statistics
  • duckduckgo.service
  • summon.service
    • summon a user via e-mail/xmpp
      • send an e-mail to flok@nurdspace.nl if you would like it if people could !summon you as well. for that an e-mail address AND/OR an xmpp/jabber address is required

• coding example: /home/ghbot/nurdspace-ircbot-plugin-python-example/template.py on the harkbot lxc

!what

• runs under ghbot user (via systemd) on nurdservices. invokes dhcp-lease-list underneath (with some awk magic)
• has a -v switch for verbose mode

spacesound

• mpd_plugin.py
  • !np / !mpd / !radio / !radiolink
  • mpd_plugin.service

logo