Flirror is a modular smartmirror application developed in Python. It consists of a simple webserver based on Flask which holds the UI and a command line application that retrieves information from different APIs (e.g. OpenWeather, Google Calendar, ...). Currently, there is only a small set of available modules, but I'm planning to add some more (see planned features and ideas).
Despite the number of commits, this project is still in an early phase, so I'm happy about any contribution!
Contents: Motivation | Architecture | Usage | Available Modules | Deploy on Raspberry | Planned features and ideas |
I mainly started this project because I wanted to build a smartmirror using a Raspberry Pi. I searched for existing projects and found a few, but none of them really suited my needs. There are a few smaller ones developed in Python, but most of them don't seem to be actively maintaned anymore. A very public one I found is for sure MagicMirror2. I think, this is a really awesome project - taking a look at all the customizable parts, contributions and custom modules that were developed in the meantime. I'm just not much of a JavaScript developer and don't like the idea of having everything in a single application.
But I got inspired by the features it provides and decided to develop my own smartmirror in Python. Maybe someone else in the Python community is also interested in a project like this.
Flirror mainly consists of two components - a webserver based on Flask and a command line application, the so called "crawler" that retrieves data from different APIs/backends (whatever you want to call it).
The webserver is mainly used to show the information that is retrieved by the crawlers. Currently, it doesn't allow any "interaction" from a user side. But maybe something like this will come in the future.
The crawler application can simply be invoked from the command line and is used
to crawl the various backends / APIs for the actual data that is displayed by
flirror-web. The crawler application supports two different modes: periodic
and immediate (default). The periodic mode will crawl all available APIs in
customizable intervals, while the immediate mode can be used as a one-shot
command to retrieve the data directly from all available backends.
To bring both components together I decided for a very simple approach, using a local SQLite databse. I mainly made this choice, because we are only storing simple key value pairs and SQLite comes out of the box with python.
Flirror can simply be installed via pip:
$ pip install flirror
or via docker:
$ docker pull felixedel/flirror
Deploying flirror via docker is simplest using docker-compose. An example
docker-compose stack can be found in the deploy/docker-compose.example.yaml
file.
Both applications - flirror-web and flirror-crawler - read their
configuration from the file path given via the FLIRROR_SETTINGS environment
variable, e.g.
$ export FLIRROR_SETTINGS=$(pwd)/settings.cfg
A basic configuration file must at least contain the path to a DATABASE_FILE
and a list of MODULES with at least one module configured.
Each entry in the MODULES list accepts the following parameters:
| Parameter | Description |
|---|---|
id | Required The ID to identify this module inside the application. |
module | Required The name of the module to use for this tile. A list of available modules can be found here |
config | Required The configuration for the specific module. Some modules come up with a default configuration, but usually this is needed to for each module. For more details on how to configure the specific module, take a look at the module's configuration part in the modules section. |
crawler | Crawler specific settings. This can be used to speficy e.g.the crawling interval for a specific module. For more details see the crawler config section. |
display | Configure the position and reloading time of a module |
An example configuration with at least one module with the minimum required parameters might look like the following:
MODULES = [
{
"id": "weather-tile",
"type": "weather",
"config": {
"city": "My hometown",
"api_key": "<your-openweathermap-api-key>",
"language": "en",
"temp_unit": "celsius",
},
"display": {
"position": 0,
},
}
]
For more detailed configuration examples, please take a look at the
settings.example.cfg file.
Each module entry defined in this configuration file will be shown as a single tile in flirror-web and will be crawled independently in flirror-crawler.
To start flirror-web, simply run the following command:
$ flirror-web
which will start a gunicorn server serving the flirror
application on http://127.0.0.1. The script accepts arbitrary parameters, so
you could further configure the gunicorn command that is executed in the end, by
e.g. specifying the number workers or changing the address. For a list of
available command line arguments, please refer to gunicorn's documentation.
If you don't want to use gunicorn, you could take a look at Flask's uWSGI guide.
To start the crawler simply run one of the following commands
# Periodic mode
$ flirror-crawler crawl --periodic
# Immediate mode
$ flirror-crawler crawl
to run the crawler either in periodic or immediate mode. In both cases flirror will look up all modules specified in the configuration file and try to retrieve the data for each one by invoking the respective crawler.
The following modules are available in flirror by default:
The clock module displays a clock either in digital or analog format. This is a pure JavaScript/CSS module, as it wouldn't make much sense to use a Python backend to retrieve the current time.
| Option | Description |
|---|---|
mode | Must be one of analog or digital to display the clock in the selected format. Default: digital |
The weather module displays the current weather information together with a forecast for the next six days. The weather information is retrieved from OpenWeather, so an OpenWeather API key is necessary to access those information. Information on how to get a free API key can be found in their How to start section.
| Option | Description |
|---|---|
api_key | Required Your personal OpenWeather API key |
language | Required The language in which the results are returned from the API (and thus displayd in flirror). For a list of available language codes, please refer to the OpenWeather multilangual support. |
city | Required The city to retrieve the weather information for. |
temp_unit | Required The unit in which the results are returned from the API (and thus displayed in flirror). |
The calendar modules displays upcoming events from a Google calendar. Currently, Flirror only supports the OAuth 2.0 for TV and Limited-Input Device Applications.
| Option | Description |
|---|---|
calendars | Required A list of google calendars to retrieve the events from. If you don't want to mix up multiple calendars in one tile, you can configure multiple calendar modules with one calendar each. Your default google calendar is usually named after your gmail address. |
max_items | The maximum number of events to show. Default: 5 |
The stocks module displays current stock values either in table format or as a time series. The information is retrieved from Alpha Vantage, so an Alpha Vantage API keys is necessary to access those information. Information on how to get a free API key can be found in their Getting started guide.
| Option | Description |
|---|---|
api_key | Required Your personal Alpha Vantage API key |
symbols | Required The list of equities you want to retrieve. Each element must be in the format ("<symbol>", "<display_name>") |
mode | One of table or series to display the stocks information in the selected format. DEfault: table |
The news module displays entries from a RSS feed. Flirror uses the feedparser package to crawl the newsfeeds. Please take a look at feedparser's documentation to get an overview about available formats which can be parsed.
| Option | Description |
|---|---|
name | Required The title to display over the news entries |
url | Required The url pointing to the RSS feed |
To install docker on raspbian OS, you can simply run the following command:
$ curl -sSL https://get.docker.com | sh
This will download the installation script and directly execute it via shell. Running the script may take some time. Afterwards, you might want to add your user (pi) to the docker group, so you can run docker without sudo:
$ sudo usermod -aG docker pi
Afterwards log out and back or reboot the Raspberry Pi via
$ sudo reboot -h
There are various ways to install docker-compose. Please see the docker-compose installation guide for more detailed information.
I personally installed docker-compose via
pipx.
Using this variant requires the python-dev and libffi-dev packages to be
installed on the system.
$ sudo apt install python-dev libffi-dev
$ python3 -m pip install --user pipx
$ python3 -m pipx ensurepath
$ pipx install docker-compose
Both componenents can be started using the docker-compose file provided in
deploy/docker-compose.example.yaml. You just need to change the latest
tag of the image used for both services to latest:armv7 since a Raspberry Pi
is using arm architecture and that needs a dedicated docker image.
Afterwards, simply run
$ docker-compose up
to start the web server and the crawler in periodic mode.
With both services running we still need to open some browser to see the actual
flirror UI. This can be done by executing the helpers/start_gui.sh helper
script. Apart from starting chromium in full screen mode pointing to the running
flirror-web instance inside the docker container, this script will also ensure
that some necessary environment variables like DISPLAY are set and that the
screen saver and energy saving mode of the X server are disabled - so the
display doesn't go into sleep mode after a few minutes.
To hide the mouse cursor, install unclutter via
$ sudo apt install unclutter
and add the following line to /home/pi/.config/lxsession/LXDE-pi/autostart
@unclutter -display :0 -noevents -grab
Content type
Image
Digest
Size
43.8 MB
Last updated
over 6 years ago
docker pull felixedel/flirror