GHBot: Difference between revisions

Revision as of 14:30, 13 August 2022

An IRC bot

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

Implemented by Flok
- github: https://github.com/folkertvanheusden/GHBot

- code examples for plugins:
  - Python: https://github.com/folkertvanheusden/nurdspace-ircbot-plugin-python-example
  - Arduino (on ESP8266/ESP32): https://github.com/folkertvanheusden/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)
- value: authenticate|plugin-command|nonce - asks a plugin to authenticate
  - each plugin that authenticates has a shared key - shared with ghbot
  - that plugin then hashes the nonce + plugin-command and encrypts it with the shared key
  - the result is put on GHBot/to/bot/command-reply
  - with this schema we can have authentication per command, with the possibility of "forgetting" or revoking the access of a certain plugin

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

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'
  - 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 SlabPi (different languages yay \o/)
!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

~~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
~~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 now longer performs multikarma etc.

~~!message (zie kiki: !boodschap)~~
- added

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

@@ Line 34: / Line 34: @@
 * topic: GHBot/from/bot/command
 ** value: register  - asks all plugins to immediately register all the commands it knows (see above)
+** value: authenticate|plugin-command|nonce - asks a plugin to authenticate
+*** each plugin that authenticates has a shared key - shared with ghbot
+*** that plugin then hashes the nonce + plugin-command and encrypts it with the shared key
+*** the result is put on GHBot/to/bot/command-reply
+*** with this schema we can have authentication per command, with the possibility of "forgetting" or revoking the access of a certain plugin
 * topic: GHBot/from/bot/parameter/prefix