GHBot: Difference between revisions

From NURDspace
No edit summary
 
(48 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== An IRC bot ==
== An IRC bot ==
* Runs on container named [[harkbot]]
* Design by [[r3boot]]
* Design by [[r3boot]]
** https://github.com/r3boot/jaken  => note: since the original design some enhancements have been done
** https://github.com/r3boot/jaken  => note: since the original design some enhancements have been done


* Implemented by [[Flok]]
* Implemented by [[Folkert]]
** github: https://github.com/folkertvanheusden/GHBot
** github: https://github.com/folkertvanheusden/GHbot


** code examples for plugins:
** code examples for plugins:
*** Python: https://github.com/folkertvanheusden/nurdspace-ircbot-plugin-python-example
*** Python: https://github.com/NURDspace/nurdspace-ircbot-plugin-python-example
*** Arduino (on ESP8266/ESP32): https://github.com/folkertvanheusden/nurdspace-ircbot-plugin-esp8266-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
*** Home Assistant integration (in Python): https://github.com/NURDspace/ghbot-hass


=== design (in short; see Jaken (r3boot) for full) ===
=== design (in short; see Jaken (r3boot) for full) ===
Line 28: Line 26:
* topic: GHBot/to/irc/'''channel'''/privmsg
* topic: GHBot/to/irc/'''channel'''/privmsg
** value: text to publish to '''channel''' - note that the '#' in the channel name must be omitted
** 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.
GHBot also sends everything it receives via IRC to MQTT topics, for the plugins to be processed.
Line 58: Line 59:
* connect a nick to a new hostname:
* connect a nick to a new hostname:
** meet '''nick'''
** 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




Line 72: Line 83:
**** %u user invoking the command
**** %u user invoking the command
**** %m like '/me'
**** %m like '/me'
**** %n post as a notice
*** returns a number with which you can delete the alias
*** returns a number with which you can delete the alias


Line 92: Line 104:
* <s>!ot-set - Updates OpenTherm thermostat setpoint through [[Jarvis|Home assistant]]</s>
* <s>!ot-set - Updates OpenTherm thermostat setpoint through [[Jarvis|Home assistant]]</s>
* <s>!sensors - Queries sensors from [[Jarvis|Home assistant]]</s>
* <s>!sensors - Queries sensors from [[Jarvis|Home assistant]]</s>
* !speak / !spreek / !dire / !sprech / !habla - Text to speach using espeak on [[SlabPi]] (different languages yay \o/)
* !speak / !spreek / !dire / !sprech / !habla - Text to speach using espeak on <s>[[SlabPi]]</s>Spacesound (different languages yay \o/) (Deligated to Melan)
* !statustoggle - (temp) manually switch the space from closed to open
* !statustoggle - (temp) manually switch the space from closed to open
* <s>!sth - temps and humidities of the different rooms</s>
* <s>!sth - temps and humidities of the different rooms</s>
Line 116: Line 128:


=== Feature Requests ===
=== Feature Requests ===
* <s>!merge new-nick old-nick</s>
* <s>[[User:buZz|buZz]] Make alias legible (like !moon 62 is aliased to .... !nowaytoknownow)</s>
** !viewalias
* [[User:buZz|buZz]] Autodescribing help for plugins
* <s>[[User:buZz|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)</s>
* <s>[[User:buZz|buZz]] add highlight of nickname to reminder notification</s> now does so!
* [[User:buZz|buZz]] give a error msg on unknown -anything- in PM , instead of silence (like on channel)
* [[User:buZz|buZz]] allow a group be a group member for ACL , so we can make a 'SD' group, and make 'members' a member of it
* <s>[[User:buZz|buZz]] add !np -v or something else that can show the album of the current playing song</s>
* <s>[[User:R3boot|r3boot]] Overzicht van plugins die herschreven moeten worden naar de nieuwe plugin structuur</s>
* <s>[[User:R3boot|r3boot]] Overzicht van plugins die herschreven moeten worden naar de nieuwe plugin structuur</s>
** zie hierboven
** zie hierboven
Line 126: Line 148:


* <s>[[User:R3boot|r3boot]] Overzicht van operaties die beheerders kunnen uitvoeren op de bot (ops documentatie)</s>
* <s>[[User:R3boot|r3boot]] Overzicht van operaties die beheerders kunnen uitvoeren op de bot (ops documentatie)</s>
* [[User:Dennis|The_Niz]] [[Parts|Partkeepr search]]
* <s>[[User:Dennis|The_Niz]] [[Parts|Partkeepr search]]</s>
** done
* <s>[[User:Dennis|The_Niz]] !btc in Eu ipv die nare dollah units</s>
* <s>[[User:Dennis|The_Niz]] !btc in Eu ipv die nare dollah units</s>
** ik heb geen conversie dingetje naar euro, suggesties welkom though
** ik heb geen conversie dingetje naar euro, suggesties welkom though
Line 135: Line 158:
* <s>[[User:Dennis|The_Niz]] !@ voor (youtube) URL titel spam</s>
* <s>[[User:Dennis|The_Niz]] !@ voor (youtube) URL titel spam</s>
** gedaan
** gedaan
* [[User:R3boot|r3boot]] Apply acceptable regex to incoming karma requests (eg: ^[a-zA-Z0-9_-]+{\+\+,--}$. This will prevent multikarma and calling the plugin multiple times.
* <s>[[User:R3boot|r3boot]] Apply acceptable regex to incoming karma requests (eg: ^[a-zA-Z0-9_-]+{\+\+,--}$. This will prevent multikarma and calling the plugin multiple times.</s>
** karma.py has been severly dumbed down and no longer performs multikarma etc.
* <s>[[User:Dennis|The_Niz]] Keep track of commands that were once available in order to create an errormsg when the plugin is down</s>
** implemented in 5db0f18ca20b3471b3a71686f949822434e64647
* <s>!message (zie kiki: !boodschap)</s>
** added
* stock quotes, see https://github.com/jlyheden/stockbot
* <s>!karma-whyup !karma-whoup !karma-whodown !karma-whydown</s> !karma-top10 !karma-bottom10 !karma-stats
** implemented as !whykarma
* <s>!op / auto-op</s>
** 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 ==
 
[[File:Ghbot.png|640px]]

Latest revision as of 14:36, 25 February 2024

An IRC bot

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

  • 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
    • 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

Ghbot.png