Bite Board-Bot

Tip

This project is a Java reimplementation of the Bite Board Bot in TypeScript, since the TypeScript version faced installation issues on Raspberry Pi devices.

A Discord bot that allows for creating custom Menu Providers that can then fetch the menu for a specific day from a specific canteen or other food location and show a preview using Google Images.

• Bite Board-Bot
  • Installation
  • Setup
    • Configuration
      • discordBotToken / discordClientId
      • dataStoragePath
      • mensaMenuImagePreviewService
      • googleImageApiKey / googleImageApiApplicationId
      • language
      • menuVotingOnUserRequest / menuVotingOnScheduledRequest
    • Inviting the bot to your server
  • Usage
    • Commands: Fetching the menu
    • Commands: Providers
    • Commands: Scheduled Fetching
  • Creating a Menu Provider
  • Raspberry Pi setup
  • License

Installation

Before being able to run the bot for the first time (java -jar ...), you need to configure the bot. See the Configuration section for more information.

git clone https://github.com/YanWittmann/bite-board-bot-java
cd bite-board-bot-java
mvn clean package
java -jar target/bite-board-bot.jar

Setup

Configuration

For this, copy the bite-board-config-template.json file into a new file called bite-board-config.json and configure the values inside according to the following instructions.

If you need to change the path to the configuration file to somewhere outside the jar file, you can do so by setting a BITE_BOARD_CONFIG_PATH environment variable in your process.

Make sure to rerun mvn clean package after changing the configuration file.

discordBotToken / discordClientId

The token is the bot token you get from the Discord Developer Portal. For this, you will need to create a new application and a bot user for it. There are plenty of tutorials on how to do this on the internet already.

• The discordBotToken is the token of the bot, which you can find under the Bot tab of your bot in the portal.

Unused:

• The discordClientId is the client ID of the bot, which you can find under the OAuth2 tab of your bot in the portal.

dataStoragePath

Is a path to a JSON file that will contain data the bot needs to store, such as user settings and periodic tasks. This file will be created if it does not exist yet. The default is a file bot-data.json in the current working directory.

mensaMenuImagePreviewService

This can be either none, googleApi or googleImages. Depending on the value, the bot will use a different service to fetch images for the menu embeds or not fetch any images at all.

• none: No images will be fetched.
• googleApi: The Google Image API will be used to fetch images, see parameters below. Up to 100 images can be fetched per day for free, after that you will need to pay for the service.
• googleImages: Google Images will be used to fetch images. This is free and the image quality is better than the API (in my opinion), although the resolution is (much) lower.

googleImageApiKey / googleImageApiApplicationId

The Google Image API key and application ID are used to fetch images for the menu embeds. You can get them from the Google Cloud Console. Configure googleApi for mensaMenuImagePreviewService to use the Google Image API.

Honestly, this is not worth it. The images from the API are just so much worse that the ones from the Google Images search. I recommend just using the Google Images search.

language

The language the bot should use for the menu embeds. Currently, en and de are supported. If you need to add your own language, you can do so by adding a new JSON file to the lang directory and putting its name in the LanguageManager.java file at the top into the list.

menuVotingOnUserRequest / menuVotingOnScheduledRequest

Can each either be set to true or false. If true, the bot will add reactions (that depend on the menu provider) to the menu embeds that allow users to vote on the menu.

Inviting the bot to your server

To invite the bot to your server, you need to create an invitation link. You can do that on the OAuth2 tab of your bot in the Discord Developer Portal as well. Make sure to allow the following permissions (at least):

Usage

This bot can fetch menus in two modes: triggered by a user command and scheduled periodic fetching.

Commands: Fetching the menu

The bot provides a /menu command that allows users to retrieve the menu for specific days or meals from supported menu providers. Use it, followed by a subcommand specifying the date for which you want to see the menu. Depending on your language, you may use your appropriate subcommands.

/menu today     | /menu heute
/menu tomorrow  | /menu morgen
/menu monday    | /menu montag
/menu tuesday   | /menu dienstag
/menu wednesday | /menu mittwoch
/menu thursday  | /menu donnerstag
/menu friday    | /menu freitag

If configured, the bot will fetch images for relevant menu items and display them alongside the menu.

Commands: Providers

You may want to specify your preferred provider for the menu by using the /menu provider command with a provider parameter.

To view all available providers, use the /menu listproviders command.

Commands: Scheduled Fetching

In addition to user-triggered commands, the bot also supports scheduled periodic fetching of menus from configured providers. This feature allows the bot to automatically post menu information at regular intervals, removing the need to manually request it each day.

To create a scheduled fetch, your user needs to have the periodic role. For security reasons, roles can only be changed by editing the bot-data.json file directly. In the users object, add a new key with your Discord tag (not id#number format or the userId) and set the roles array to include periodic. You can easily create such an entry by executing the /menu provider command once on your user.

Then, run the following command in the Discord channel where you want the menu to be posted. Note that the time parameter is in UTC, meaning you will have to calculate based on your timezone. You can also use the /menu time command to get the current UTC time as reference. In order to be able to post the menu for the next day(s), you can set an add time in minutes that will add the given amount of minutes to the current time before determining the day for which to fetch the menu.

/menu schedule time:18:00:00 provider:Hochschule Mannheim add:1440

Your JSON bot data could look like this afterward:

{
  "sendDailyMenuInfo": [{
    "addTime": 1440,
    "provider": "Hochschule Mannheim",
    "time": "18:00:00",
    "channelId": "some-channel-id"
  }],
  "users": [{
    "preferredMenuProvider": "Hochschule Mannheim",
    "roles": ["periodic"],
    "userId": "some-user-id"
  }]
}

Creating a Menu Provider

To create a new menu provider, you need to create a new class that extends the MenuItemsProvider class. See the HochschuleMannheimTagessichtMenuProvider for an example.

After finishing it, you need to register your provider in the BiteBoardBotEntrypoint file by passing an instance into the BiteBoardBot constructor.

Raspberry Pi setup

Any java version >= 8 will work, this for example installed java 17:

sudo apt update
sudo apt upgrade
sudo apt install default-jdk
java -version

Copy via ssh the jar file to the Raspberry Pi after building it (replace your user and paths):

scp bite-board-bot.jar [email protected]:/home/user/workspace/bite-board-bot
[email protected]'s password:
bite-board-bot.jar                              100%   66KB   1.7MB/s   00:00

Start the bot with screen to be able to access it later again:

screen -S bite-board-bot -d -m java -jar bite-board-bot.jar
screen -r bite-board-bot

To detach a screen session: Ctrl+a followed by d. Note the lower case.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.