Skip to content

stustanet/bernd-lauert

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 Cannot retrieve latest commit at this time.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Bernd Lauert

A matrix chatbot, originally designed for the StuStaNet e.V. administrator chatroom (#admins:stusta.de), written in python. Adopted for the RBG Cybergroup.

Requirements:

All required python modules are listed in the requirements.txt file. Furthermore the bot needs read and write permissions in the installation folder for correct execution.

Execution:

Specify the login credentials for the bot, as well as target rooms to join, in the provided config.ini file. When specifying target rooms, the internal ID (!suchalongidwehavehere:server.org) must be used in order enable room-specific plugins. If specifying multiple rooms, the IDs need to be separated by a semicolon (';'). Quotes should be generally omitted in the file.

After the bot has been configured, issue:

python bernd -c <config_file> [-m <mode>]

Possible modes of operation are cmd (default) and daemon. In daemon mode, the bot won't wait for user input and join plugin child threads instead. This mode enables seamless invocation as an e.g. systemd service. However, daemon mode requires a modified version of the underlying MatrixBotAPI, which returns the created thread upon invocation of the start_polling() function.

Structure:

The bot itself only uses the basic functionality of the matrix_bot_api module to establish a matrix connection. All higher functionality is implemented in plugin files. These plugins need to be located in the plugins folder.

Every plugin needs to define a register_to(bot) function, which is called upon plugin loading, and a HELP_DESC variable, containing a string with a short textual description of its features.

For interaction with matrix services, respective modules need to be imported. Consider this short example of an echo plugin for demonstration purposes:

from matrix_bot_api.mcommand_handler import MCommandHandler

# Define a HELP_DESC, which describes the new functionality
HELP_DESC = ("!echo\t\t-\tEcho back the given string\n")

# plugin loading function, executed upon startup
def register_to(bot):

    # Callback functions, registered with MCommandHandler/MRegexHandler are
    # provided with a matrix room object, in which the event has been received,
    # and the event data itself. Events in matrix are JSON objects and can be
    # easily accessed as follows:   json_value = event['json_key']
    def echo_callback(room, event):
        args = event['content']['body'].split()
        args.pop(0)

        # Interaction with matrix is conducted through the room object. Consider
        # the documentation of matrix_client.client/api for further information
        room.send_text(event['sender'] + ': ' + ' '.join(args))

    # Add a command handler waiting for the echo command
    # This command handler reacts upon the command "!echo" and then invokes
    # the echo_callback function defined above
    echo_handler = MCommandHandler("echo", echo_callback)

    # register the handler with the running bot
    bot.add_handler(echo_handler)

Newly written plugins are loaded automatically once they are placed in the plugins folder and fulfill all specified requirements.

Commands:

As the functionality of the bot depends heavily on the installed plugins, use the !help command, in order to display the currently available features. The displayed configuration is automatically generated at bot startup from the plugin description texts.

Releases

No releases published

Packages

No packages published

Languages

  • Python 99.2%
  • Nix 0.8%