A MQTT to IRC / IRC to MQTT bridge or bot. Call it what you like.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea
src/main/java/de/dobermai/mqttbot
.gitignore
LICENSE.txt
README.asciidoc
mqtt-irc-bot.iml
pom.xml

README.asciidoc

MQTTBot

MQTTBot is a IRC-to-MQTT and MQTT-to-IRC "bridge". MQTTBot (as you can guess from the name) is an IRC bot which is connected to a MQTT broker and can publish and subscribe to the broker. So you can forward the IRC messages to your favourite MQTT topics or you can post received MQTT messages to the IRC chat.

Why would I want a IRC-MQTT bridge?

Admit it, you always wanted to chat with your MQTT enabled devices in an IRC chat. Your devices are now able to chat with humans. Internet of Things just got real.

Seriously?

Perhaps. This bot was written out of curiosity (I have never written an IRC bot before) and fun. There are however some interesting use cases which can be implemented with that bot. You could for instance use this bot to bridge all messages of an IRC channel to a MQTT broker and your Arduino (which subscribes to the said broker) beeps whenever your name was mentioned in the IRC chat.

Another interesting use case could be to send messages you (and hopefully all other people in the channel) care about to the IRC chat. It is recommended that you use a MQTT broker which implements a sophisticated security concept for topics to avoid abuse or spamming. HiveMQ offers such a functionality.

Structure

IRC to MQTT

The IRC Bot publishes all messages from IRC channels to MQTT topics. Since the # character cannot be used in MQTT topic names, it is replaced by % in topic names by default.

The root mapping of IRC chats to MQTT topics is the following:

$IRC_PREFIX/$IRC_ROOM

Example: $IRC_PREFIX is mqttbot/irc. The room we connect to is #superawesometest. The root topic for this room would be:

mqttbot/irc/%superawesometest

The following subtopics under $IRC_PREFIX/$IRC_ROOM are available:

Table 1. Subtopics

messages

all messages of the IRC room are published to this topic

messages/$NICKNAME

all messages of the user with the nickname are published to this topic

users

everytime the users in the chatroom change, a retained message with all currently connected users is published

topic

everytime the topic of the IRC room changes a retained message is published

MQTT to IRC

It is possible to publish messages to a specific IRC channel via MQTT. Since the # character cannot be used in MQTT topic names, it is replaced by % in topic names by default. To send a message to an IRC chat with MQTT, publish to:

$IRC_PREFIX/$IRC_ROOM

Example: $IRC_PREFIX is mqttbot/irc. The room we connect to is #superawesometest. To publish to this channel, publish to mqttbot/irc/%superawesometest

Caution
DO.NOT.ABUSE
This features MUST NOT be abused for spamming IRC channels. You will most likely be banned faster than you think when doing this. Drop your black hat and put on your yellow smiley-face hat.

Packaging

Just run

mvn package

to generate a executable jar file.

Preparation & Starting MQTTBot

Steps before starting MQTTBot
  1. Create a config.properties file and place in directory of MQTTBot.

  2. Double check if MQTT and IRC properties are correct

  3. Start MQTTBot with java -jar XXX.jar (where XXX is the name of the MQTTBot artifact

Caution
Properties file
Before starting MQTTBot the first time, be sure to place a config.properties file in the same directory where the jar file of MQTTBot is located. See the configuration documentation for a list of all allowed properties.

Configuration

MQTTBot uses Apache Commons Configuration under the hood, which allows sane property file handling, including the usage of lists and variable interpolation.

Properties

All available properties are listed below:

Table 2. MQTT Properties
Property Default Value Description

broker.host

broker.mqttdashboard.com

The hostname or IP of the MQTT message broker

broker.port

1883

The port of the MQTT broker

mqtt.keepAlive

60

The MQTT keepalive interval in seconds

mqtt.clientId

mqtt-bot

The MQTT clientId.

mqtt.cleanSession

true

If the bot should connect to the broker with a clean session

mqtt.username

The MQTT username. Defaults to no username.

mqtt.password

The MQTT password. Defaults to no password.

mqtt.topicPrefix

irc

The MQTT topic prefix when publishing.

mqtt.ircChannelPrefix

%

The prefix of the "#" channel sign for irc chats on mqtt topics. Needed because # ist not a valid mqtt topic character

Tip
You should at least change the MQTT clientId.
Table 3. IRC Properties
Property Default Value Description

irc.hostname

irc.freenode.net

The hostname of the IRC server.

irc.port

6667

The port of the IRC server

irc.nickName

mqtt_bot

Nickname of the Bot in IRC rooms

irc.channels

#mqttbottest, #secondmqttbottest

A list of channels the Bot should connect to.

Example properties file

TODO!!!

TODOs

This is not um.. production ready yet. There are still many things to do

  • Unit tests are completely missing.

  • MQTT and IRC reconnecting is not implemented yet