{"id":13689558,"url":"https://github.com/vranki/hemppa","last_synced_at":"2026-01-19T18:08:32.299Z","repository":{"id":36842452,"uuid":"226931692","full_name":"vranki/hemppa","owner":"vranki","description":"Generic modular bot for Matrix (and via it irc, telegram, slack, etc..)","archived":false,"fork":false,"pushed_at":"2025-04-25T13:50:58.000Z","size":511,"stargazers_count":160,"open_issues_count":50,"forks_count":37,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-05-02T00:32:07.985Z","etag":null,"topics":["hacktoberfest","matrix","matrix-bot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vranki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-09T17:43:05.000Z","updated_at":"2025-04-15T15:56:39.000Z","dependencies_parsed_at":"2023-01-17T05:45:22.814Z","dependency_job_id":"1f8210a4-2fb5-410a-a57d-1a936b956149","html_url":"https://github.com/vranki/hemppa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vranki/hemppa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vranki%2Fhemppa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vranki%2Fhemppa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vranki%2Fhemppa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vranki%2Fhemppa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vranki","download_url":"https://codeload.github.com/vranki/hemppa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vranki%2Fhemppa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28578996,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T17:42:58.221Z","status":"ssl_error","status_checked_at":"2026-01-19T17:40:54.158Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","matrix","matrix-bot"],"created_at":"2024-08-02T15:01:52.810Z","updated_at":"2026-01-19T18:08:32.267Z","avatar_url":"https://github.com/vranki.png","language":"Python","funding_links":[],"categories":["hacktoberfest"],"sub_categories":[],"readme":"# Hemppa - generic modular Matrix bot\n\nThis bot is meant to be super easy platform to write Matrix bot functionality\nin Python. It uses matrix-nio library https://github.com/poljar/matrix-nio/ for\nMatrix communications.\n\nZero configuration except Matrix account info is needed. Everything else can\nbe done with bot commands.\n\nType !help in room with this bot running to list active modules.\n\nIf you don't want some modules, just delete the files from modules directory or\ndisable them with !bot disable command.\n\nEnd-to-end encryption is currently not supported by bot but should be doable.\nBot won't respond to commands in e2ee rooms. PR for enabling e2ee is welcome!\n\nSupport room: #hemppa:hacklab.fi - https://matrix.to/#/#hemppa:hacklab.fi\n\n## Hint: RSS Bridge\n\nRSS Bridge is awesome project that creates RSS feeds for sites that don't have them:\nhttps://github.com/RSS-Bridge/rss-bridge\n\nIf you want bot to notify on new posts on a service, check out if RSS Bridge\nsupports it! You can use the stock Matrix RSS bot to subscribe to feeds created\nby RSS bridge.\n\n## Module list\n\n### Bot\n\nBot management commands.\n\n* !bot status - print bot status information\n* !bot ping - print the ping time between the server and the bot\n* !bot version - print version and uptime of the bot\n* !bot stats - show statistics on matrix users seen by bot\n\nThe following must be done as the bot owner:\n\n* !bot enable [module] - enable module\n* !bot disable [module] - disable module\n* !bot quit - quit the bot process\n* !bot reload - reload all bot modules\n* !bot export - export all bot settings as json\n* !bot export [module] - export a module's settings as json\n* !bot import [json object] - Update all bot settings from json\n* !bot import [module] [json object] - Update a module's settings from json\n* !bot import [module] [key ...] [json object] - Update a sub-object in a module from json\n  * Example: !bot import alias aliases {\"osm\": \"loc\", \"sh\": \"cmd\"}\n* !bot logs [module] ([count]) - Print the [count] most recent messages the given module has reported\n* !bot uricache (view|clean|clear) - View the uri cache, or clear it.\nThe uri cache prevents the bot from uploading a blob from a url repeatedly\n* !bot leave - ask bot to leave this room\n* !bot modules - list all modules including enabled status\n* !bot rooms - list rooms the bot is on\n\n### Help\n\nPrints help on existing modules.\n\n* !help - get short help for all currently-enabled modules\n* !help [module] - get long help for the given module, or short help if unavailable\n* !sethelp msg (on|yes|1) - Configure !help to respond to !help requests via a direct message, instead of in the current room\n(Must be done as bot owner)\n\n### Alias\n\nAdd or remove aliases for a module.\n\n* !alias list - List all aliases\n* !alias add [newname] [module] - Define an alias for [module] (Must be done as bot owner)\n* !alias remove [name] - Remove [name] as an alias (Must be done as bot owner)\n\n### Echo\n\nSimple example module that just echoes what user said.\n\n* !echo Hello, world!\n\n### Metar\n\nAviation weather metar service access.\n\n* !metar eftp\n\n### TAF\n\nAviation weather TAF service access.\n\n* !taf eftp\n\n### NOTAM\n\nAviation NOTAM data access. Currently supports only Finnish airports - implement other countries where\ndata is available.\n\n* !notam efjm\n\n### Teamup\n\nCan access Teamup ( https://teamup.com/ ) calendar. Teamup has nice API and is easier to set up than Google so\nprefer it if possible. This bot polls the calendar every 5 minutes and notifies the room of any changes.\n\nHowto:\n\n* Create a calendar in Teamup https://teamup.com/\n* Get api key at https://teamup.com/api-keys/request\n* !teamup apikey [your api key]\n* !teamup add [calendar id]\n\nCommands:\n\n* !teamup apikey [apikey] - set api key (Must be done as bot owner)\n* !teamup - list upcoming events in calendar\n* !teamup add [calendar id] - add calendar to this room (Must be done as room admin)\n* !teamup del [calendar id] - delete calendar from this room (Must be done as room admin)\n* !teamup list - list calendars in this room\n* !teamup poll - poll now for changes (Must be done as bot owner)\n\n### Google Calendar\n\nCan access a google calendar in a room. This is a bit pain to set up, sorry.\n\nTo set up, you'll need to generate oauth2 credentials.json file - see https://console.developers.google.com/apis/credentials\n\nRun the bot on *local* machine as OAuth2 wants to open localhost url in your browser. I haven't found out an easy way to\ndo this on server.\n\nThere is a empty credentials.json file in the bot directory. Replace it with yours. When credentials.json is present, you must\nauthenticate the bot to access calendar. There will be a link in console like this:\n\n``` text\nPlease visit this URL to authorize this application: https://accounts.google.com/o/oauth2/auth?response_type=code\u0026client_id=907....\n```\n\nOpen the link and authenticate as needed. A new file token.pickle will be created in the directory and bot will read it in future.\nSave the token.pickle and ship it with the bot to your server.\n\nNow the bot should be usable.\n\nUse !googlecal add [calendar id] to add new calendar to a room. The bot lists availble calendar ID's on startup and you can find them\nin google calendar.\n\nCommands:\n\n* !googlecal - Show next 10 events in calendar\n* !googlecal today - Show today's events\n* !googlecal add [calendar id] - Add new calendar to room (Must be done as room admin)\n* !googlecal del [calendar id] - Delete calendar from room (Must be done as room admin)\n* !googlecal list - List calendars in this room\n\nNOTE: disabled by default\n\n### Cron\n\nCan schedule things to be done.\n\nCommands:\n\n* !cron daily [hour] [command] - Run command on start of hour (Must be done as room admin)\n* !cron list - List commands in this room\n* !cron clear - Clear command s in this room (Must be done as room admin)\n* !cron time - Print the current datetime and time zone that the cron command will use (time zone set using the `TZ` environment variable)\n\nExamples:\n\n* !cron daily 19 \"It is now 19 o clock\"\n* !cron daily 8 \"!googlecal today\"\n\n### Location\n\nCan search OpenStreetMaps for locations and send Matrix location events from them. Translates Matrix location events into OSM links.\n\nCommands:\n\n* !loc [location] - search for location\n* !loc enable     - enable location to link translation in this room (must be done as room admin)\n* !loc disable    - disable location to link translation in this room (must be done as room admin)\n\nExample:\n\n* !loc Tampere\n\n### Room\n\nThis module is for interacting with the room that the commands are being executed on.\n\n* !room servers                                     Lists the servers in the room\n* !room joined                                      Responds with the joined members count\n* !room banned                                      Lists the banned users and their provided reason\n* !room kicked                                      Lists the kicked users and their provided reason\n* !room state [event type] [optional state key]     Gets a state event with given event type and optional state key\n* !room tombstone [target]                          Creates a tombstone event pointing to target room. Target room can be alias (starting with #) or id (starting with !). User must be admin in the room.\n\nNote on tombstone: If using alias, bot must be present in target room. This is the preferred way. If using id, make sure it's correct, as it's not validated!\nTombstoning requires power level for room upgrade. Make sure bot has it in the room.\n\n### Welcome to Room\n\nWhen configured in a room, the bot will monitor a room for new users and send new users a welcome message 1:1. It will then notify bot owners of the new user. It will also, optionally, notify of user departure.\n\nCommands:\n\n* !welcome_room welcome_message [message]        Sets the welcome message, along with other variables needed to detect new users.\n* !welcome_room notify_departure [True/False]    Sets whether bot owners will be notified of departure from room. Defaults to False.\n* !welcome_room settings                         Shows the current settings for the welcome_room module.\n\n### Welcome to Server\n\nAs a server admin, the bot will monitor new user creation on the server and send the welcome message to new users 1:1. It will then notify bot owners of the new user.\n\nCommands:\n\n* !welcome_server welcome_message [message]    Sets the welcome message, along with other variables needed to detect new users.\n* !welcome_server settings                     Shows current settings for the welcome_server module\n\n### Slow polling services\n\nThese have the same usage - you can add one or more accounts to a room and bot polls the accounts.\nNew posts are sent to room.  Polls only randomly every 30 to 60 minutes to keep traffic at minimum.\n\nCommands:\n\nPrefix with selected service, for example \"!ig add accountname\" or \"!teamup list\"\n\n* add [accountname] - Add account to this room (Must be done as room admin)\n* del [accountname] - Delete account from room (Must be done as room admin)\n* list - List accounts in room\n* poll - Poll for new items  (Must be done as bot owner)\n* clear - Clear all accounts from this room  (Must be done as room admin)\n* debug - Show some debug information for accounts in room\n\n#### Instagram\n\nPolls instagram account(s). Uses instagram scraper library\nwithout any authentication or api key.\n\nSee: https://github.com/realsirjoe/instagram-scraper/\n\nNOTE: disabled by default\n\n#### Matrix Messaging API (mxma)\n\nThis is a simple API to ask bot to send messages in Matrix using JSON file from external service.\n\nYou'll need an API endpoint (webserver) that contains a message queue. It must respond with following JSON to a HTTP GET request:\n\n```json\n{\n   \"messages\":[\n      {\n         \"to\": \"@example:matrix.org\",\n         \"title\": \"Room Title\",\n         \"message\": \"Hello from Hemppa\"\n      },\n      {\n         \"to\": \"@another:matrix.user\",\n         \"title\": \"Room 2 Title\",\n         \"message\": \"Second message\"\n      }\n   ]\n}\n```\n\nNormally you want to clear the messages when the endpoint is GETted or the messages will repeat\nevery time bot updates itself.\n\nThese messages are sent to given Matrix users in private message with given room title.\nMessages are sent \"best effort\" - if sending fails, it will be logged to bot output log.\n\nThen just:\n\n* !mxma add http://url.to.the/endpoint.json\n\nmxma requires all commands to be run as bot owner.\n\n#### SpaceAPI\n\nPolls the status of Hack- and Makerspaces that provide an endpoint\nthat conforms to the [SpaceAPI](https://spaceapi.io/) protocol and notifies\nabout changes of the opening status.\n\nTo add a new endpoint simply use\n`!spaceapi add https://hackspace.example.org/status`\n\nFor Admins: A template and I18N can be configured via settings of\nthe module. Use `!bot export spacepi`, then change the\nsettings and import again with `!bot import spacepi SETTINGS`.\n\n### Url\n\nWatches all messages in a room and if a url is found tries to fetch it and\nspit out the title if found.\n\nDefaults to off and needs to be activated on every room you want this.\n\nYou can choose to send titles as notices (as in Matrix spec) or normal\nmessages (IRC users might prefer this). This is a global setting currently.\nYou can set a blacklist to ignore URLs containing words from the blacklist.\n\nCommands:\n\n* !url status          - show current status\n* !url title           - spam titles to room\n* !url description     - spam descriptions\n* !url both            - spam both title and description\n* !url off             - stop spamming\n* !url text            - send titles as normal text (must be owner)\n* !url notice          - sends titles as notices (must be owner)\n* !url blacklist list  - blacklist comma separated list of url substrings\n* !url blacklist clear - clear blacklist\n\nExample:\n\n* !url status\n* !url blacklist www.youtube.com,www.somethingelse.com\n\nNOTE: Disabled by default, i.e. you also need to enable it before activating it\n\n### Cmd\n\nCan be used to pre-configure shell commands run by bot. This is easy way to add\nsecurity issues to your bot so be careful.\n\nPre-defined commands can be set only by bot owner, but anyone can run them.\nIt's your responsibility as owner to make sure you don't allow running anything dangerous.\n\nCommands have 5 second timeout so don't try to run long processes.\n\nEnviron variables seen by commands:\n\n* MATRIX_USER: User who ran the command\n* MATRIX_ROOM: Room the command was run (avoid using, may cause vulnerabilities)\n\nCommands:\n\n* !cmd run command              - Run command \"command\" (Must be done as bot owner)\n* !cmd add \"cmdname\" command    - Add new named command \"command\"  (Must be done as bot owner)\n* !cmd remove \"cmdname\"         - Remove named command (Must be done as bot owner)\n* !cmd list                     - List named commands\n* !cmd \"cmdname\"                - Run a named command\n\nExample:\n\n* !cmd run \"hostname\"\n* !cmd add systemstats \"uname -a \u0026\u0026 uptime\"\n* !cmd systemstats\n* !cmd add df \"df -h\"\n* !cmd add whoami \"echo You are $MATRIX_USER in room $MATRIX_ROOM.\"\n\n### Astronomy Picture of the Day\n\nUpload and send latest astronomy picture of the day to the room.\nSee https://apod.nasa.gov/apod/astropix.html\n\nCommand:\n\n* !apod - Sends latest Astronomy Picture of the Day to the room\n* !apod YYYY-MM-DD - date of the APOD image to retrieve (ex. !apod 2020-03-15)\n* !apod stats - show information about uri cache\n* !apod clear - clear uri cache (Must be done as admin)\n* !apod apikey [api-key] - set the nasa api key (Must be done as bot owner)\n* !apod help - show command help\n* !apod avatar (YYYY-MM-DD) - additionally, set roomavatar to the astronomy pic of the day (ignored if not admin in room)\n\nAPI Key:\n\nThe module uses a demo API Key which can be replaced by your own api key by setting the environment variable `APOD_API_KEY` or by setting the api key as a bot owner with command `!apod apikey [apikey]`.\n\nYou can create one at https://api.nasa.gov/#signUp\n\n### XKCD\n\nFetch comic strips from [XKCD](https://xkcd.com) (A webcomic of romance,\nsarcasm, math, and language) and post them to the room.\n\nCommand:\n\n* !xkcd - Sends latest XKCD comic strip to the room\n* !xkcd ID - Sends xkcd number ID to the room\n* !xkcd help - show command help\n\n\n### Inspirobot\n\nQuery a randomly generated inspirational poster from https://inspirobot.me/ upload and send to the room.\n\nCommand:\n\n* !inspire - Generate inspiration and post to the room\n* !inspire help - Show this help\n\n### User Status\n\nThis is a substitute for matrix' (element's?) missing user status feature.\nSave a custom (status) message for users and allows to query them.\n\nCommands:\n\n* !status clear - clear my status\n* !status show [user] - show the status of the given user. If no user is given, show all status messages\n* !status help - show this text\n* !status [status] - set your status (your status must not begin with another command word.)\n\n\n### Wolfram Alpha\n\nMake queries to Wolfram Alpha\n\nYou'll need to get an appid from https://products.wolframalpha.com/simple-api/documentation/\n\nExamples:\n\n* !wa 1+1\n* !wafull airspeed of unladen swallow\n\nCommands:\n\n* !wa [query] - Query wolfram alpha and return the primary pod.\n* !wafull [query] - Query wolfram alpha and return all pods.\n* !wa appid [appid] - Set appid (must be done as bot owner)\n\n### OGN Field Log (FLOG)\n\nOpen Glider Network maintains a unified tracking platform for gliders, drones and other aircraft.\n\nRead more about OGN at https://www.glidernet.org/\n\nFLOG module supports showing field logs for OGN receivers and can display live\nfield log in a room. It can also show latest known location of an aircraft\nusing !sar command.\n\nIt uses FlightBook instance at https://flightbook.glidernet.org/\n\nFlightBook sources and documentation at https://gitlab.com/lemoidului/ogn-flightbook\n\n\nReal life field log output looks something like:\n\n```\nFlights at Chateau Arnoux St Auban (LFMX) 2021-04-09:\n13:36-18:01 04:24 F-CLDG JS-3 18M FM 2291m\n13:46-··:··       F-CIFF Arcus T FP\n13:57-17:13 03:15 JS-1 C21 72 2636m\n14:08-17:30 03:22 ZS-GCC JS-1 C21 FD 2754m\n18:29-··:··       F-CLDG JS-3 18M FM\n```\n\nCommands and examples:\n\n(You must be room admin for all commands)\n\n* !flog station EFJM - set the default station to track for this room\n* !flog rmstation - remove station from this room\n* !flog - Show field flog for the room's station (can be used by any user)\n* !flog EFJM - Show field flog for any station (can be used by any user)\n* !flog status - print status of this room\n* !flog live - enable live field log for this room\n* !flog rmlive - disable live field log for this room\n* !sar OH-123 - Send latest known location of aircraft OH-123\n\nNOTE: disabled by default\n\n### Jitsi\n\nIf enabled, Jitsi calls created with Matrix clients will be sent as text messages\nto rooms, allowing non-matrix users to join them.\n\n### Mastodon\n\nSend toots to Mastodon. You can login to Mastodon with the bot and toot with it.\n\nNormal login is personal - it's mapped to your Matrix ID.\n\nRoom login overrides personal login and allows room admins to toot to a specified account.\n\nYou can limit usage to bot owners only or make it public.\n\nNote: You can subscribe to Mastodon users and hashtags with stock RSS feed integration.\nMastodon generates the feeds automatically!\n\nCommands:\n\n* !md status - print status of mastodon module\n* !md login [instanceurl] [e-mail] [password] - log in your Matrix user to Mastodon instance (do in private chat!)\n* !md toot [toot] - send a toot message. If said in a room with per-room login, user must be a admin in the room.\n* !md logout - log out the user from the bot\n* !md roomlogin [room] [instanceurl] [e-mail] [password] - same as login but assigns a per-room mastodon account  (do in private chat!)\n* !md roomlogout - Say in a room that has per-room login. This will remove the login. Must be room admin.\n* !md setpublic - ANY user can use login command to login and use the Mastodon module (must be done as bot owner)\n* !md setprivate - Only bot owners can use Mastodon module (default) (must be done as bot owner)\n* !md clear - Clear all logins from the bot\n\nExample commands:\n\n* !md login https://my.instance/ me@email.invalid r00tm3\n* !md roomlogin #myroom:matrix.org https://my.instance/ me@email.invalid r00tm3\n\n### Relay bridge\n\nBridges two or more Matrix rooms together via relaybot.\n\nNote: Room ID is not same as room alias! Rooms can exist without aliases so ID's are more flexible. Room id is usually in format !123LotOfRandomChars:server.org\n\nTo get room ID, it's in Element Web room settings | Advanced | Internal room ID\n\nBefore bridging the bot must be present on both rooms.\n\nCommands:\n\n* !relay bridge [roomid] - Bridge room with given ID to this room (must be done as bot owner)\n* !relay list - List bridged rooms (and their index numbers) (must be done as bot owner)\n* !relay unbridge [number] - Remove the given bridge number (must be done as bot owner)\n\nFile uploads, joins, leaves or other special events are not (yet) handled. Contributions welcome.\n\nRelaybots are stupid. Please prefer real Matrix bridges to this. Sometimes there's no alternative.\n\n### Printing\n\nWith this module you can set up a room to print any uploaded files on a specified printer.\nThe printer must be visible to bot via CUPS.\n\nCommands (all can be done by bot owner only):\n\n* !printing list - Lists available printers and their rooms\n* !printing setroomprinter [printername] - Assignes given printer to this room\n* !printing rmroomprinter - Deletes printer from this room\n* !printing setpapersize [papersize] - Set global paper size. Default is A4. See printer settings for valid values.\n\nThe module sends the files to CUPS for printing so please see CUPS documentation\non what works and what doesn't.\n\nTested formats: PDF, JPG, PNG\n\nSVG files are printed as text currently, avoid printing them.\n\nThis module is disabled by default.\n\n### Giphy\n\nCan be used to post a picture from giphy given a query string.\n\nAPI Key:\n\nThe module has no API Key set up by default. You have to provide an api key by using the relevant command.\n\nRead the documentation to create one at https://developers.giphy.com/docs/api\n\nCommands:\n\n* !giphy apikey [apikey]    - Set api key (Must be done as bot owner)\n* !giphy [query]            - Post the first image result from giphy for the given [query]\n\n\nExample:\n\n* !giphy test\n\n### Gfycat\n\nNOTE: This module is not working at the moment - gfycat now needs API key\n\nCan be used to post a picture from Gfycat given a query string.\n\nCommands:\n\n* !gfycat [query]   - Post the first image result from gfycat for the given [query]\n\nExample:\n\n* !gfycat test\n\n### Tautulli\n\nCan be used to fetch recently added information from Tautulli or receive Tautulli recently added notification webhook\n\nCommands:\n\n* !tautulli apikey [apikey]             - Set api key (Must be done as bot owner)\n* !tautulli movie                       - Show the last 10 recently added movies to Plex library monitered by Tautulli\n* !tautulli show                        - Show the last 10 recently added tv series epsiodes to Plex library monitered by Tautulli\n* !tautulli artist                      - Show the last 10 recently added music artists to Plex library monitered by Tautulli\n* !tautulli add [room_id] encrypted     - Add the provided encrypted [room_id] to the list of rooms to post the recently added notifications received by the webhook\n* !tautulli add [room_id] plain         - Add the provided unencrypted [room_id] to the list of rooms to post the recently added notifications received by the webhook\n* !tautulli remove [room_id] encrypted  - Remove the provided encrypted [room_id] to the list of rooms to post the recently added notifications received by the webhook\n* !tautulli remove [room_id] plain      - Remove the provided unencrypted [room_id] to the list of rooms to post the recently added notifications received by the webhook\n\nTautulli instance and API Key:\n\nThe module work with an instance of Tautulli accessible on URL defined by env variable `TAUTULLI_URL`\nIn order to load art pictures you need to define an instance of Plex Media Server with its token as well by the two env variables `PLEX_MEDIA_SERVER_URL` and `PLEX_MEDIA_SERVER_TOKEN`\nYou have to provide an api key by using the relevant command.\n\nEnviron variables seen by command:\n\n* PLEX_MEDIA_SERVER_URL: Url accessible from the machine to an instance of Plex Media Server\n* PLEX_MEDIA_SERVER_TOKEN: Plex Token for the instance of Plex Media Server\n* TAUTULLI_URL: Url accessible from the machine to an instance of Tautulli\n* TAUTULLI_NOTIFIER_ADDR: Listening address for the Tautulli webhook handler target\n* TAUTULLI_NOTIFIER_PORT: Listening port for the Tautulli webhook handler target\n* BOT_OWNERS: Owner of the rooms in the list for the notification webhook\n\nDocker environment:\n\nSince the module needs access to the source of the running Tautulli instance volumes on both Docker (hemppa and Tautulli) should be defined and being visible each other.\nWhen running on Docker the env variables seen by command should be defined for the bot instance.\n\nExample:\n\n* !tautulli movie\n* !tautulli add !OGEhHVWSdvArJzumhm:matrix.org plain\n* !tautulli remove !OGEhHVWSdvArJzumhm:matrix.org plain\n\n### Github based asset management\n\nThis module was written for asset (machines, tasks and todo) management by\nmis-using GitHub issues and labels. It has been designed to be used with hackerspace\nenvironment but can be extended to any purpose.\n\n#### Github project setup\n\n* Create labels to github that represent for example different machines and spaces.\nYou can create any number of them.\n* Define label colors for each type of asset. These are called domains in this module.\nFor example set all machine labels to be #B60205 and space labels to be #0E8A16. These\ncan be easily picked from color chooser.\n* Edit the repository description and add a json block describing the\nlabel domains and their colors (array format supports multiple colors per domain). For example:\n\n```\nHackerspace machines, todo and stuff. domains={\"koneet\":[\"#BFDADC\",\"#0CBBF0\",\"#0CBBF0\",\"#E15D19\",\"#ED49CF\"],\"tilat\":[\"#0E8A16\",\"#1E8A16\"]}\n```\n\nMake sure you type the description on one line - this is a silly Github limitation.\n\n* When creating issues, assign machine and/or space labels for them.\nFor example, if a wood lathe is broken, create issue with labels\n\"Wood lathe\" and \"Wood working room\".\n\n#### Usage\n\n* !ghproj setrepo [repository] - Set repository for this room (room admin only)\n* !ghproj repo - Shows which repository this room tracks\n* !ghproj rmrepo - Remove repository from this room (room admin only)\n* !ghproj [domain] - List machine statuses in this domain\n\nRepository name must be in format TampereHacklab/Inventaario - you can\nuse this as a example to see how the labels work.\n\n### PeerTube search\n\nSearches PeerTube instances for videos. Uses Sepia Serch at https://sepiasearch.org/\nby default, but you can set any single instance to search on.\n\n#### Usage\n\n* !pt [query]           - Search for exactly one video matching query\n* !ptall [query]        - Search up to 15 videos matching query\n* !pt setinstance [url] - Set instance url, must end with / (example: https://peertube.cpy.re/)\n* !pt showinstance      - Print which instance is used\n\n### User management\n\nAdmin commands to manage users and some utilities.\n\nYou can classify users based on MXID to get stats on where users come from.\n\n#### Usage\n\n* !users list [pattern]  - List users matching wildcard pattern in this room (must be owner)\n* !users listall [pattern]  - List users matching wildcard pattern globally (must be owner)\n* !users kick [pattern]  - Kick users matching wildcard pattern from room (must be admin in room)\n* !users classify add [name] [pattern] - Add a classification pattern (must be owner)\n* !users classify list - List classifications\n* !users classify del [name] - Delete classification (must be owner)\n* !users roomstats - List how many users are in each class in this room\n* !users stats - List how many users are in each class globally as seen by bot\n\nExample:\n\n* !users classify add matrix.org @*:matrix.org\n* !users classify add libera.chat @*:libera.chat\n* !users classify add discord @*discordpuppet*:*\n* !users stats\n* !users roomstats\n\n### RASP (Gliding Weather forecast)\n\nCurrently only Finnish RASP supported. Uses data from http://ennuste.ilmailuliitto.fi/\n\n#### Usage\n\n* !rasp [day] [hour]     - Fetch RASP for specified day and hour\n\nDay and hour can be omitted - fetches today's forecast if not set.\nPR welcome for supporting other data sources.\n\n### Mumble\n\nShow information about a configured mumble server,\nincluding version, how many users are connected, and ping time.\n\n#### Usage\n\n* !mumble                                 - Show info about the configured mumble server\n- !mumble (set|setserver) [host] ([port]) - Set the configured mumble server\n\n### Nitter\n\nReads Twitter links from room, replaces domain with nitter, removes query parameters and posts link to room.\n\n#### Usage\n\n* !nitter enable     - enable converting twitter links to nitter links in this room (must be done as room admin)\n* !nitter disable    - disable converting twitter links to nitter links in this room (must be done as room admin)\n\n### Wikipedia\n\nSearches Wikipedia for a given query and returns the first result summary and link.\n\n#### Usage\n\n* !wikipedia [query] - Search Wikipedia for query\n\n### Dice Roll\n\nRolls dice in XdY format.\n\n* !roll 1d20 - roll a single d20\n* !roll 1d20+4 - a skill check or attack roll\n* !roll 1d20+1 adv - a skill check or attack roll with advantage\n* !roll 1d20-1 dis - a skill check or attack roll with disadvantage\n* !roll help - show help info\n\nFor more syntax help, see \u003chttps://d20.readthedocs.io/en/latest/start.html#dice-syntax\u003e.\n\n### Matrix -\u003e MQTT Forwarding\n\nCan forward messages from Matrix room to MQTT topics.\nMust be bot owner to use.\n\n* !mqtt forward #room:matrix.org test.mosquitto.org hemppa_test_topic - Setup a forward from room to given MQTT server and topic name\n* !mqtt status - show status\n* !mqtt remove !roomid  - Remove existing forward\n* !mqtt clear - Clear all forwards\n\n(Currently just sends message bodies as string - might change to JSON later?)\n\n## Bot setup\n\n* Create a Matrix user\n* Log in as the newly created user (easiest is Element Web in private window)\n* Get user's access token (In Element Web see Settings / Help \u0026 about)\n\n## Running locally\n\nRun something like (tested on Ubuntu):\n\n``` bash\nsudo apt install python3-pip libcups2-dev libatlas-base-dev gcc\nsudo pip3 install pipenv\npipenv shell\npipenv install --pre                       (this takes ages, go make a sandwich)\nMATRIX_USER=\"@user:matrix.org\" MATRIX_ACCESS_TOKEN=\"MDAxOGxvYlotofcharacters53CgYAYFgo\" MATRIX_SERVER=\"https://matrix.org\" JOIN_ON_INVITE=True BOT_OWNERS=@botowner:matrix.org\n python3 bot.py\n```\n\nNOTE: The Pipfile does not define the python version as it is always strict and causes problems. See https://github.com/pypa/pipenv/issues/1050 . Python 3.7 and 3.8 should both work fine.\n\n## Running locally with systemd unit file (Raspberry Pi etc)\n\nFirst modify run.sh and make sure Hemppa starts successfully with it.\n\nThere's a systemd unit file you can use. It assumes hemppa is installed to /opt/hemppa and\nis run as user pi in group pi. Note: this is probably not the smartest way to do this, feel free\nto do a PR for better way.\n\nIf your user is not pi, modify hemppa.service first.\n\n``` bash\nsudo ln -s `pwd` /opt/hemppa\nsudo ln -s `pwd`/hemppa.service /lib/systemd/system\nsudo systemctl daemon-reload\nsudo systemctl enable hemppa.service\nsudo systemctl start hemppa.service\nsudo systemctl status hemppa.service\n```\n\nStatus should show \"Active: active (running)\"\n\n## Running with Docker\n\nCreate .env file and set variables:\n\n``` bash\nMATRIX_USER=@user:matrix.org\nMATRIX_ACCESS_TOKEN=MDAxOGxvYlotofcharacters53CgYAYFgo\nMATRIX_SERVER=https://matrix.org\nJOIN_ON_INVITE=True\nBOT_OWNERS=@user1:matrix.org,@user2:matrix.org\nDEBUG=False\nTZ=America/New_York\n```\n\nNote: without quotes!\n\nJust run:\n\n``` bash\ndocker-compose up\n```\n\n## Env variables\n\n`MATRIX_USER` is the full MXID (not just username) of the Matrix user. `MATRIX_ACCESS_TOKEN`\nand `MATRIX_SERVER` should be url to the user's server (non-delegated server). Set `JOIN_ON_INVITE` (default true)\nto false if you don't want the bot automatically joining rooms.\n\nYou can get access token by logging in with Element Android and looking from Settings / Help \u0026 About.\n\n`BOT_OWNERS` is a comma-separated list of matrix id's for the owners of the bot.\nSome commands require sender to be bot owner.\nTypically set your own id into it.\n\n`OWNERS_ONLY` is an optional variable once defined only the owners can operate the bot (this is a form of whitelisting)\n\n`INVITE_WHITELIST` (default empty) is an optional comma-separated list of matrix id's to restrict the acceptance of invites into rooms of the bot to users or servers. It supports wild cards: Example value: `@user:matrix.org,@*:myserver.org`\n\n`LEAVE_EMPTY_ROOMS` (default true) if this is set to false, the bot will stay in empty rooms\n\n__*ATTENTION:*__ Don't include bot itself in `BOT_OWNERS` if cron or any other module that can cause bot to send custom commands is used, as it could potentially be used to run owner commands as the bot itself.\n\nTo enable debugging for the root logger set `DEBUG=True`.\n\n`TZ` takes any valid [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) value and sets the bot server to the appropriate zone.\n\n## Module API\n\nJust write a python file with desired command name and place it in modules. See current modules for\nexamples. No need to register it anywhere else.\n\n*Simple skeleton for a bot module:*\n```python\n\nclass MatrixModule(BotModule):\n\n    async def matrix_message(self, bot, room, event):\n        args = event.body.split()\n        args.pop(0)\n\n        # Echo what they said back\n        self.logger.debug(f\"room: {room.name} sender: {event.sender} wants an echo\")\n        await bot.send_text(room, ' '.join(args), event=None)\n\n    def help(self):\n        return 'Echoes back what user has said'\n\n```\n\n### Functions\n\n* matrix_start - Called once on startup\n* async matrix_message - Called when a message is sent to room starting with !module_name\n* matrix_stop - Called once before exit\n* async matrix_poll - Called every 10 seconds\n* help - Return one-liner help text\n* get_settings - Must return a dict object that can be converted to JSON and sent to server\n* set_settings - Load these settings. It should be the same JSON you returned in previous get_settings\n\nYou only need to implement the ones you need. See existing bots for examples.\n\n## Bot API\n```python\nclass Bot:\n    async def send_msg(self, mxid, roomname, message):\n        \"\"\"\n\n        :param mxid: A Matrix user id to send the message to\n        :param roomname: A Matrix room id to send the message to\n        :param message: Text to be sent as message\n        :return bool: Success upon sending the message\n        \"\"\"\n\n    async def send_text(self, room, body, event=None, msgtype=\"m.notice\", bot_ignore=False):\n        \"\"\"\n\n        :param room: A MatrixRoom the text should be send to\n        :param body: Textual content of the message\n        :param event: The event to reply to\n        :param msgtype: The message type for the room https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes\n        :param bot_ignore: Flag to mark the message to be ignored by the bot\n        :return:\n        \"\"\"\n\n    async def send_html(self, room, html, plaintext, event=None, msgtype=\"m.notice\", bot_ignore=False):\n        \"\"\"\n\n        :param room: A MatrixRoom the html should be send to\n        :param html: Html content of the message\n        :param plaintext: Plaintext content of the message\n        :param event: The event to reply to\n        :param msgtype: The message type for the room https://matrix.org/docs/spec/client_server/latest#m-room-message-msgtypes\n        :param bot_ignore: Flag to mark the message to be ignored by the bot\n        :return:\n        \"\"\"\n\n    async def send_image(self, room, url, body, event=None, mimetype=None, width=None, height=None, size=None):\n        \"\"\"\n\n        :param room: A MatrixRoom the image should be send to\n        :param url: A MXC-Uri https://matrix.org/docs/spec/client_server/r0.6.0#mxc-uri\n        :param body: A textual representation of the image\n        :param event: The event to reply to\n        :param mimetype: The mimetype of the image\n        :param width: Width in pixel of the image\n        :param height: Height in pixel of the image\n        :param size: Size in bytes of the image\n        :return:\n        \"\"\"\n\n    async def upload_image(self, url, blob=False, blob_content_type=\"image/png\"):\n        \"\"\"\n\n        :param url: Url of binary content of the image to upload\n        :param blob: Flag to indicate if the first param is an url or a binary content\n        :param blob_content_type: Content type of the image in case of binary content\n        :return: A MXC-Uri https://matrix.org/docs/spec/client_server/r0.6.0#mxc-uri, Content type, Width, Height, Image size in bytes\n        \"\"\"\n\n\n    async def upload_and_send_image(self, room, url, event=None, text=None, blob=False, blob_content_type=\"image/png\"):\n        \"\"\"\n\n        :param room: A MatrixRoom the image should be send to after uploading\n        :param url: Url of binary content of the image to upload\n        :param event: The event to reply to\n        :param text: A textual representation of the image\n        :param blob: Flag to indicate if the second param is an url or a binary content\n        :param blob_content_type: Content type of the image in case of binary content\n        :return:\n        \"\"\"\n    async def send_location(self, room, body, latitude, longitude, event=None bot_ignore=False):\n        \"\"\"\n\n        :param room: A MatrixRoom the html should be send to\n        :param html: Html content of the message\n        :param body: Plaintext content of the message\n        :param latitude: Latitude in WGS84 coordinates (float)\n        :param longitude: Longitude in WGS84 coordinates (float)\n        :param event: The event to reply to\n        :param bot_ignore: Flag to mark the message to be ignored by the bot\n        :return:\n        \"\"\"\n```\n\n### Logging\n\nUses [python logging facility](https://docs.python.org/3/library/logging.html) to print information to the console. Customize it to your needs editing `config/logging.yml`.\nSee [logging.config documentation](https://docs.python.org/3/library/logging.config.html) for further information.\n\nUse `self.logger` in your module to print information to the console.\n\nModule settings are stored in Matrix account data.\n\n### Ignoring text messages\n\nIf you want to send a m.text message that bot should always ignore, set \"org.vranki.hemppa.ignore\" property in the event. Bot will ignore events with this set.\nSet the bot_ignore parameter to True in sender functions to acheive this.\n\nIf you write a module that installs a custom message handler, use bot.should_ignore_event(event) to check if event should be ignored.\n\n### Aliasing modules\n\nA module can declare its own _aliases_ with the `add_module_aliases` command.\nYou probably want to call it during `matrix_start`:\n\n```python\nclass MatrixModule(BotModule):\n\n    def matrix_start(self, bot):\n        super().matrix_start(bot)\n        self.add_module_aliases(bot, ['newname', 'anothername'])\n```\n\nThen you can call this module with its original name, `!newname`, or `!another-name`.\n(Like module names, Hemppa ignores non-alphanumeric characters in aliases.)\n\n## Contributing\n\nIf you write a new module, please make a PR if it's something useful for others.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvranki%2Fhemppa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvranki%2Fhemppa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvranki%2Fhemppa/lists"}