Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/holgerausb/teamspeak3-to-mqtt

Script to check if buddies are online on a Teamspeak server and set their status to mqtt
https://github.com/holgerausb/teamspeak3-to-mqtt

homebridge homebridge-mqtt mqtt teamspeak3

Last synced: 8 days ago
JSON representation

Script to check if buddies are online on a Teamspeak server and set their status to mqtt

Awesome Lists containing this project

README 

        
# Teamspeak3-to-MQTT

A script that detects if buddies are logged in on a Teamspeak3 server and sets their status to MQTT.



## Why

I wanted to be informed when one of my buddies is logged into my Teamspeak3 server, even if I am not sitting at the computer.



This script uses the telnet interface of a Teamspeak3 server to determine which users (clients) are currently online. It compares the client_database_id to see if my friends are online and sends the presence status to a mqtt-broker. Here you can then pick up the status via an existing Smarthome system and let for example a lamp blink.



## Prerequisites

* **You should host a Teamspeak3 server yourself or ask your hoster if you are allowed to run such a script on the telnet interface and with what minimum interval! You could be blocked otherwise!!!**

* You must be server admin of the Teamspeak server

* The script is a bash script for Linux. You should have basic knowledge in Linux and know how to use the Linux console.

* You need `expect` for the query over the telnet protocol. So you might need to install that. On Debian like systems just `apt install expect`

* You need to have access to a MQTT broker like 'mosquitto', locally or somewhere else.

* To send the result to an MQTT broker, please `apt install mosquitto-clients`. Of course, you can also change the script to perform an other action directly here. But remember that the script is executed every x minutes. In my case Homebridge takes care that an action is triggered only at the first detection of presence.



## Preparation

The first thing you need to do, is to collect and write down some data by hand. I'd suggest using a ssh console from a workstation, so you can copy&paste some things. Start your Teamspeak3 client and connect to the server. You must be a server admin. In the menu select Tools>Server Query Login. Choose a name for the query user. After OK the system will tell you your password, write it down.



Now you have to start a telnet query on the Linux console. The default port for Telnet on Teamspeak servers is 10011. Even if the hoster sets up several virtual client servers on one machine, one telnet port is usually sufficient for all of them. If the port is not correct you have to ask your provider.



`telnet servername-or-ip 10011`

Your will get a welcome message. You should copy this text and save in your text editor on your desktop pc. We'll need (parts of) this to detect if this is our ts3 server. Should look something like this:



```

Trying 123.123.xxx.xxx...

Connected to localhost.

Escape character is '^]'.

TS3

Welcome to the TeamSpeak 3 ServerQuery interface, type "help" for a list of commands and "help " for information on a specific command.

```



Later I will use the first part of the last line as a pattern in `ts3welcome="Welcome to the TeamSpeak 3 ServerQuery interface"`



After the welcome message you must provide your query user credentials:



`login queryname secretpassword`



you should get an `error id=0 msg=ok` as an answer. Then you need to know which is your server ID:



`whoami`



which should give you a long list of parameters, your ID is `client_origin_server_id=xx`. Now you need to put this number to the next command:



`use 123`



Next command gives you a list of available Channels.



`channellist`



Copy this list and paste it into a text editor or text file. After each pipe symbol `|` press enter to get a readable list, one channel per line. If you want to monitor only some of the channels you need their `cid`.



Last command gives you a list of logged in clients (the users). You need to do this, when yor buddies are online:



`clientlist`



Once again, copy this list to a text editor and hit Enter after each pipe. Then write down the `client_database_id` of your friends that you want to be informed about when they come online.



## Installation and configuration



Now place the script `ts3-to-mqtt.sh` from this repo to /usr/local/bin. Make it executable:



`sudo chmod +x /usr/local/bin/ts3-to-mqtt.sh`



Now copy the file `ts3-to-mqtt.conf` from this repo to `/etc/ts3-to-mqtt/` and open this with your editor to enter your configuration data.



Here are some additional hints about some of the parameters:



### mybuddies

This is an array, please keep the brackets () arround and do ___not___ set quotation marks arround the brackets. Multiple cid are seperated by spaces. e.g.:

```

mybuddies=(1234)                  # only one buddy

mybuddies=(1230 1231 1232 4433)   # multiple buddies

```

### channels

This one will be set as the middle part of a regular expression, so beware of the format, e.g. "(1200|1201)" will combined to the search pattern "cid=(1200|1201)[^0-9]".

```

channels="[0-9]*"           # scan ALL channels

channels="1234"             # scan only one channel, id 1234

channels="(1234)"           # scan only one channel, id 1234

channels="(1201|1202|1300)" # scan given CIDs, seperate by pipe symbol

channels="99999"            # disable channel-scan, with an unused cid

```

### entree_cid

Some admins chose to have a single channel with low permissions for guests, while only the normal users have the right to move these guests to the real used channels. To be informed, when guests are waiting to be moved you can set the channals cid here. Set to an unused cid, if you dont want to use this feature. This one is part of a regular expression as in 'channels'.

```

entree_CID="1200"         # scan one channel for ANY users

entree_CID="(1200)"       # scan one channel for ANY users

entree_CID="(1200|1201)"  # scan two channels for ANY users

entree_CID="99999"        # disable entree-scan, with an unused cid

```

## Test the script

Use two console windows. In the first you subscribe to the mosquitto-broker to see, what the script is doing:



`mosquitto_sub -h localhost -p 1883 -F '%I \e[92m%t \e[96m%p\e[0m' -t ts3/#`



-F is just for coloring the output, you might need to adjust -t with your choosen topic and add more options like your credentials for mqtt if needed.



Start your Teamspeak client and log in to your server.



Now go to the second console window and start the script `ts3-to-mqtt.sh` and control on the other console window what happened. If you set your own client id into mybuddies, you can controll if all the channels work as intended. Change channel and start the script again. Logout in TS3 and start script again. test it when no others are online and with buddies online and maybe with guests.



## Set a cron job for automation

### **ONCE AGAIN: Beware that you testet everything well (last step) and have permissions from your hoster to run this bot before activating the cron job**



Copy the file `ts3-to-mqtt-cron` to your home-path, then you should check/edit on which hours the bot-script should run. Then you should replace all 'root' in the file by your normal user. There is no need to run the script as root user. After that, move this file to /etc/cron.d



## Legal

* Teamspeak is a trademark of TeamSpeak Systems, Inc.

* Homekit and Apple are trademarks of Apple Inc.