Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/roataway/telegram-bot
A Telegram bot for reporting ETAs for public transport in Chișinău, Moldova
https://github.com/roataway/telegram-bot
csv moldova mqtt public-transport telegram
Last synced: about 1 month ago
JSON representation
A Telegram bot for reporting ETAs for public transport in Chișinău, Moldova
- Host: GitHub
- URL: https://github.com/roataway/telegram-bot
- Owner: roataway
- License: agpl-3.0
- Created: 2019-03-02T11:22:22.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-08T04:54:50.000Z (about 2 years ago)
- Last Synced: 2023-05-10T21:20:16.322Z (over 1 year ago)
- Topics: csv, moldova, mqtt, public-transport, telegram
- Language: Python
- Homepage: http://t.me/roataway_bot
- Size: 928 KB
- Stars: 12
- Watchers: 2
- Forks: 3
- Open Issues: 9
-
Metadata Files:
- Readme: readme.rst
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
.. image:: https://travis-ci.org/roataway/telegram-bot.svg?branch=master
:target: https://travis-ci.org/roataway/telegram-bot
.. image:: https://img.shields.io/github/license/roataway/telegram-bot.svg
:alt: GitHub license
:target: https://github.com/roataway/telegram-bot/blob/master/LICENSE
.. image:: https://img.shields.io/badge/zulip-join_developer_chat-blue.svg
:alt: Chat with the developers on Zulip
:target: https://roataway.zulipchat.com/
.. image:: https://img.shields.io/badge/telegram-use%20chat%20bot-blue.svg?logo=telegram
:alt: Use the chat bot on Telegram
:target: http://t.me/roataway_bot
Overview
========
A Telegram bot to provide ETA for public transport in Chișinău. A live instance is available at http://t.me/roataway_bot.
The bot is written in Python and it was tested with 3.6, though earlier versions will work too, if you install the backported version of the ``dataclasses`` module.
Discussions and development support
===================================
Head to to ask questions about the code and its structure, suggest new features or ask for tips on how to get started with running your own copy of the bot.
How to run it
=============
Prerequisites
-------------
#. Talk to @BotFather to register your bot and get a token, as described here: https://core.telegram.org/bots#6-botfather
#. Make a copy of ``res/config-sample.yaml`` to your own config file, e.g. ``config-development.yaml``, supplying the required information in the file
#. Replicate the environment using ``virtualenv`` or ``pipenv``, as described below
#. When done, run it with ``python main.py res/config-development.yaml``
The credentials as well as the server connection details are deliberately not a part of this repository. They can be found on rtec.dekart.com/infodash. The ability to figure it out on your own is the qualification barrier for getting started with this bot. Note that ``infodash`` uses WebSTOMP, rather than MQTT; however, the credentials are the same.
Virtualenv
----------
#. Create the virtualenv ``virtualenv venv-infopanel-chatbot`` to install the dependencies in it
#. Activate the venv with ``source venv-infopanel-chatbot/bin/activate``
#. Install the dependencies with ``pip install -r requirements.txt``
Pipenv
------
#. Install pipenv ``pip install pipenv``
#. Then run ``pipenv install --dev``. It will deal automatically with the venv creation and dependecy installing
Technical details
=================
The bot uses MQTT to subscribe to updates related to ETAs and the locations of trolleybuses.
Message formats
---------------
There are 2 types of messages that are received via MQTT at the moment, all payloads are in JSON format:
1. ETA updates that contain a list of estimates for the next couple of incoming transports. Such messages arrive in batches, approximately twice per minute:
::
{
"station_id": 17, # the station ID to which the prediction refers
"name": "str. 31 August - sosire" # the name of the station
"eta": {
"30": [ # the route number to which the prediction refers
[3, "3898"], # 3 minutes until board "3898" arrives
[22, "3913"] # 22 minutes until board "3913" arrives
]
},
}
2. Transport coordinates, which contain data about the last known location and speed of a given trolleybus. These are sent every ~6s:
::
{
"rtu_id": "004", # internal identifier in the backend, you can ignore it
"board": "3900", # the board number, it is written on the trolleybuses themselves
"route": "30", # human-readable name of route (may contain letters)
"lat": "47.027388",
"lon": "28.885762",
"dir": "0", # direction of motion, measured in degrees. Note that the
# coordinate system is _not_ cartesian, but the one you see
# on a compass. North is up at 0, East is right at 90,
# South is down at 180, West is right, at 270 degrees.
"speed": 0, # in km/h
}
The JSON may contain other keys, do not rely on them if they're not documented.
Station details
---------------
The information about supported stations is loaded from CSV files located in ``res/routes``, the format is ``station_id, station_order, station_name, direction``. The identifiers are generated by the RTEC database, we just have to assume they are constants.
The resources in ``res/routes/drafts`` are treated as work in progress, and are ignored when the data are loaded.
How to contribute
=================
For historical reasons, the code, comments and the instructions are written in English. Ideally, you should follow the same conventions. When opening issues, you can describe them in Romanian or Russian, besides English.
If you made any changes, send a pull request, explaining what you've done and why you've done it.
If you need any help, just ask.
Before commit
-------------
1. Run ``make autoformat`` to format all ``.py`` files
2. Run ``make verify`` and examine the output, looking for issues that need to be addressed
Building the readme
-------------------
#. Install ``rst2html`` (on Debian and its derivatives: ``sudo apt install docutils-common``).
#. Run ``rst2html readme.rst > readme.html`` to render the output and make sure it looks good.
Bot configuration
=================
To set a lit of commands, go to @BotFather and send ``/setcommands`` for the bot, with the following data::
prognosis - Vezi prognoza pentru o rută
feedback - Transmite sugestiile sau întrebările tale
help - Află cum îți pot fi de folos
about - Despre mine
Notes on obtaining ``feedback_chat_id``, it is a unique chat identifier, which you need if you want the bot to post messages somewhere. You can get this number using several methods:
#. Go to ``https://api.telegram.org/bot/getUpdates`` and look around
#. Or add ``@RawDataBot`` to the group or the channel in question, and watch its debug output as you post a message. Don't forget to kick it out of the group once you've got the number.
Contributors and credits
========================
* Roata wăy relies on an external data stream. None of the features of this bot would work without the backend and the hardware designed for deployment on the trolleybuses themselves.
* The production bot instance is hosted on a server generously provided by ``name withheld``.
* Initial proof of concept written by ``name withheld #2``.
* Others listed here: https://github.com/roataway/telegram-bot/graphs/contributors
* How about 👉 **you** 👈?