2019-12-09 22:30:06 +02:00
|
|
|
# Hemppa - generic modular Matrix bot
|
|
|
|
|
2019-12-12 21:38:19 +02:00
|
|
|
This bot is meant to be super easy platform to write Matrix bot functionality
|
|
|
|
in Python. It uses matrix-nio library https://github.com/poljar/matrix-nio/ for
|
|
|
|
Matrix communications.
|
|
|
|
|
|
|
|
Zero configuration except minimal Matrix account info is needed. Everything else can
|
|
|
|
be done with bot commands.
|
2019-12-09 22:30:06 +02:00
|
|
|
|
|
|
|
Type !help in room with this bot running to list active modules.
|
2019-12-09 19:54:57 +02:00
|
|
|
|
2019-12-12 21:38:19 +02:00
|
|
|
If you don't want some modules, just delete the files from modules directory.
|
|
|
|
|
2019-12-29 17:28:31 +02:00
|
|
|
Support room: #hemppa:hacklab.fi - https://matrix.to/#/#hemppa:hacklab.fi
|
|
|
|
|
2019-12-09 20:24:51 +02:00
|
|
|
## Module list
|
|
|
|
|
2020-01-05 00:28:57 +02:00
|
|
|
### Bot
|
|
|
|
|
|
|
|
Bot management commands.
|
|
|
|
|
2020-01-06 00:33:42 +02:00
|
|
|
* !bot version - print version and uptime of the bot
|
2020-01-05 00:28:57 +02:00
|
|
|
* !bot quit - quit the bot process (Must be done as bot owner)
|
2020-01-06 00:33:42 +02:00
|
|
|
* !bot reload - reload all bot modules (Must be done as bot owner)
|
|
|
|
* !bot stats - show statistics on matrix users seen by bot
|
2020-01-05 00:28:57 +02:00
|
|
|
|
2019-12-09 22:30:06 +02:00
|
|
|
### Help
|
|
|
|
|
|
|
|
Prints help on existing modules.
|
2019-12-09 20:24:51 +02:00
|
|
|
|
|
|
|
### Echo
|
|
|
|
|
2019-12-09 22:30:06 +02:00
|
|
|
Simple example module that just echoes what user said.
|
|
|
|
|
2020-01-05 00:28:57 +02:00
|
|
|
* !echo Hello, world!
|
|
|
|
|
2019-12-09 22:30:06 +02:00
|
|
|
### Metar
|
|
|
|
|
|
|
|
Aviation weather metar service access.
|
|
|
|
|
2020-01-05 00:28:57 +02:00
|
|
|
* !metar eftp
|
|
|
|
|
2019-12-10 19:03:19 +02:00
|
|
|
### TAF
|
2019-12-09 22:30:06 +02:00
|
|
|
|
|
|
|
Aviation weather TAF service access.
|
|
|
|
|
2020-01-05 00:28:57 +02:00
|
|
|
* !taf eftp
|
|
|
|
|
2019-12-12 21:16:50 +02:00
|
|
|
### Teamup
|
|
|
|
|
|
|
|
Can access Teamup ( https://teamup.com/ ) calendar. Teamup has nice API and is easier to set up than Google so
|
|
|
|
prefer it if possible. This bot polls the calendar every 5 minutes and notifies the room of any changes.
|
|
|
|
|
|
|
|
Howto:
|
|
|
|
|
|
|
|
* Create a calendar in Teamup https://teamup.com/
|
|
|
|
* Get api key at https://teamup.com/api-keys/request
|
2019-12-25 20:49:20 +02:00
|
|
|
* !teamup apikey [your api key]
|
|
|
|
* !teamup add [calendar id]
|
2019-12-12 21:16:50 +02:00
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
2019-12-25 20:49:20 +02:00
|
|
|
* !teamup apikey [apikey] - set api key (Must be done as bot owner)
|
2019-12-12 22:10:25 +02:00
|
|
|
* !teamup - list upcoming events in calendar
|
2019-12-25 20:49:20 +02:00
|
|
|
* !teamup add [calendar id] - add calendar to this room (Must be done as room admin)
|
|
|
|
* !teamup del [calendar id] - delete calendar from this room (Must be done as room admin)
|
2019-12-12 21:16:50 +02:00
|
|
|
* !teamup list - list calendars in this room
|
2019-12-25 23:58:36 +02:00
|
|
|
* !teamup poll - poll now for changes (Must be done as bot owner)
|
2019-12-12 21:16:50 +02:00
|
|
|
|
2019-12-10 18:05:40 +02:00
|
|
|
### Google Calendar
|
2019-12-09 22:30:06 +02:00
|
|
|
|
2019-12-10 18:05:40 +02:00
|
|
|
Can access a google calendar in a room. This is a bit pain to set up, sorry.
|
2019-12-09 22:30:06 +02:00
|
|
|
|
2019-12-10 23:43:08 +02:00
|
|
|
To set up, you'll need to generate oauth2 credentials.json file - see https://console.developers.google.com/apis/credentials
|
|
|
|
|
|
|
|
Run the bot on *local* machine as OAuth2 wants to open localhost url in your browser. I haven't found out an easy way to
|
|
|
|
do this on server.
|
2019-12-09 20:24:51 +02:00
|
|
|
|
2019-12-23 18:34:58 +02:00
|
|
|
There is a empty credentials.json file in the bot directory. Replace it with yours. When credentials.json is present, you must
|
|
|
|
authenticate the bot to access calendar. There will be a link in console like this:
|
2019-12-09 22:30:06 +02:00
|
|
|
|
|
|
|
``` text
|
|
|
|
Please visit this URL to authorize this application: https://accounts.google.com/o/oauth2/auth?response_type=code&client_id=907....
|
|
|
|
```
|
|
|
|
|
2019-12-10 19:03:19 +02:00
|
|
|
Open the link and authenticate as needed. A new file token.pickle will be created in the directory and bot will read it in future.
|
2019-12-23 18:34:58 +02:00
|
|
|
Save the token.pickle and ship it with the bot to your server.
|
2019-12-09 22:30:06 +02:00
|
|
|
|
|
|
|
Now the bot should be usable.
|
|
|
|
|
|
|
|
Use !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
|
|
|
|
in google calendar.
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
|
|
|
* !googlecal - Show next 10 events in calendar
|
|
|
|
* !googlecal today - Show today's events
|
2019-12-25 20:49:20 +02:00
|
|
|
* !googlecal add [calendar id] - Add new calendar to room (Must be done as room admin)
|
|
|
|
* !googlecal del [calendar id] - Delete calendar from room (Must be done as room admin)
|
2019-12-10 23:43:08 +02:00
|
|
|
* !googlecal list - List calendars in this room
|
2019-12-09 22:30:06 +02:00
|
|
|
|
2019-12-10 19:03:19 +02:00
|
|
|
### Cron
|
|
|
|
|
|
|
|
Can schedule things to be done.
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
2019-12-25 20:49:20 +02:00
|
|
|
* !cron daily [hour] [command] - Run command on start of hour (Must be done as room admin)
|
2019-12-10 19:03:19 +02:00
|
|
|
* !cron list - List commands in this room
|
2019-12-25 20:49:20 +02:00
|
|
|
* !cron clear - Clear command s in this room (Must be done as room admin)
|
2019-12-10 19:03:19 +02:00
|
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
|
|
* !cron daily 19 "It is now 19 o clock"
|
|
|
|
* !cron daily 8 "!googlecal today"
|
|
|
|
|
2019-12-10 22:00:15 +02:00
|
|
|
### Location
|
|
|
|
|
|
|
|
Can search OpenStreetMaps for locations and send Matrix location events from them. Translates Matrix location events into OSM links.
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
|
|
|
* !loc [location] - search for location
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
* !loc Tampere
|
|
|
|
|
2019-12-25 23:58:36 +02:00
|
|
|
### Instagram
|
|
|
|
|
|
|
|
Polls instagram account(s) and posts new items to the room. Uses instagram scraper library
|
2019-12-30 23:16:39 +02:00
|
|
|
without any authentication or api key so it polls only randomly every 30 to 60 minutes to keep traffic at minimum.
|
2019-12-25 23:58:36 +02:00
|
|
|
|
|
|
|
See: https://github.com/realsirjoe/instagram-scraper/
|
|
|
|
|
|
|
|
Commands:
|
|
|
|
|
|
|
|
* !ig add [accountname] - Add instagram account to this room (Must be done as room admin)
|
|
|
|
* !ig del [accountname] - Delete instagram account from room (Must be done as room admin)
|
|
|
|
* !ig list - List accounts in room
|
|
|
|
* !ig poll - Poll for new items (Must be done as bot owner)
|
2019-12-30 23:16:39 +02:00
|
|
|
* !ig clear - Clear all ig accounts from this room (Must be done as room admin)
|
2019-12-25 23:58:36 +02:00
|
|
|
|
2019-12-09 22:30:06 +02:00
|
|
|
## Bot setup
|
2019-12-09 19:54:57 +02:00
|
|
|
|
|
|
|
* Create a Matrix user
|
|
|
|
* Get user's access token - In Riot Web see Settings / Help & about
|
|
|
|
|
|
|
|
## Running on host
|
|
|
|
|
2019-12-23 18:04:45 +02:00
|
|
|
Run something like (tested on Ubuntu):
|
2019-12-09 19:54:57 +02:00
|
|
|
|
|
|
|
``` bash
|
2019-12-23 18:04:45 +02:00
|
|
|
sudo apt install python3-pip
|
|
|
|
sudo pip3 install pipenv
|
2019-12-09 19:54:57 +02:00
|
|
|
pipenv shell
|
2019-12-23 18:04:45 +02:00
|
|
|
pipenv install --pre
|
2019-12-25 20:49:20 +02:00
|
|
|
MATRIX_USER="@user:matrix.org" MATRIX_ACCESS_TOKEN="MDAxOGxvYlotofcharacters53CgYAYFgo" MATRIX_SERVER="https://matrix.org" JOIN_ON_INVITE=True BOT_OWNERS=@botowner:matrix.org
|
|
|
|
python3 bot.py
|
2019-12-09 19:54:57 +02:00
|
|
|
```
|
|
|
|
|
|
|
|
## Running with Docker
|
|
|
|
|
|
|
|
Create .env file and set variables:
|
|
|
|
|
|
|
|
``` bash
|
|
|
|
MATRIX_USER=@user:matrix.org
|
|
|
|
MATRIX_ACCESS_TOKEN=MDAxOGxvYlotofcharacters53CgYAYFgo
|
|
|
|
MATRIX_SERVER=https://matrix.org
|
|
|
|
JOIN_ON_INVITE=True
|
2019-12-25 20:49:20 +02:00
|
|
|
BOT_OWNERS=@user1:matrix.org,@user2:matrix.org
|
2019-12-09 19:54:57 +02:00
|
|
|
```
|
|
|
|
|
|
|
|
Note: without quotes!
|
|
|
|
|
|
|
|
Just run:
|
|
|
|
|
|
|
|
``` bash
|
|
|
|
docker-compose up
|
|
|
|
```
|
|
|
|
|
|
|
|
## Env variables
|
|
|
|
|
|
|
|
User, access token and server should be self-explanatory. Set JOIN_ON_INVITE to anything if you want the bot to
|
2019-12-30 23:16:39 +02:00
|
|
|
join invites automatically (do not set it if you don't want it to join).
|
2019-12-09 19:54:57 +02:00
|
|
|
|
|
|
|
You can set MATRIX_PASSWORD if you want to get access token. Normally you can use Riot to get it.
|
|
|
|
|
2019-12-25 20:49:20 +02:00
|
|
|
BOT_OWNERS is a comma-separated list of matrix id's for the owners of the bot. Some commands require
|
|
|
|
sender to be bot owner. Typically set your own id into it. 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.
|
|
|
|
|
2019-12-09 22:30:06 +02:00
|
|
|
## Module API
|
|
|
|
|
|
|
|
Just write a python file with desired command name and place it in modules. See current modules for
|
|
|
|
examples. No need to register it anywhere else.
|
|
|
|
|
|
|
|
Functions:
|
|
|
|
|
|
|
|
* matrix_start - Called once on startup
|
|
|
|
* async matrix_message - Called when a message is sent to room starting with !module_name
|
|
|
|
* matrix_stop - Called once before exit
|
|
|
|
* async matrix_poll - Called every 10 seconds
|
|
|
|
* help - Return one-liner help text
|
2019-12-10 19:03:19 +02:00
|
|
|
* get_settings - Must return a dict object that can be converted to JSON and sent to server
|
|
|
|
* set_settings - Load these settings. It should be the same JSON you returned in previous get_settings
|
2019-12-09 22:30:06 +02:00
|
|
|
|
2019-12-12 21:38:19 +02:00
|
|
|
You only need to implement the ones you need. See existing bots for examples.
|
|
|
|
|
|
|
|
Module settings are stored in Matrix account data.
|
2019-12-10 19:03:19 +02:00
|
|
|
|
2019-12-12 21:38:19 +02:00
|
|
|
If you write a new module, please make a PR if it's something useful for others.
|