mrusme / lemon

Lemon

Lemon – LED Monitor – is a $79.43 opensource alternative to LaMetric that supports GitHub-, IFTTT- and Zapier-webhooks and even integrates with Pushover!

More examples here, here, here & here.

Requirements

• WiFi
• A Raspberry Pi with a Pimoroni Unicorn Hat HD
• Raspbian Desktop (not lite/headless!) on its microSD card
• A GitHub account

Installation

On your Raspberry:

$ raspi-config nonint do_spi 0
$ reboot
$ aptitude install python3 python3-pip python3-dev python3-spidev libtiff5-dev libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libwebp-dev libharfbuzz-dev libfribidi-dev tcl8.6-dev tk8.6-dev python-tk
$ pip3 install gunicorn falcon pillow ujson unicornhathd
$ # If you want to enable Pushover integration:
$ pip3 install py-pushover-open-client
$ # If you want to enable InfluxDB integration:
$ pip3 install influxdb
$ cd /opt
$ git clone https://github.com/mrusme/lemon.git
$ ln -s /opt/lemon/init.d/lemon /etc/init.d/lemon
$ update-rc.d lemon defaults

Lemon will now be run automatically every time your Raspberry starts.

Running manually

$ cd lemon/
$ ./lemon.sh

Configuration

Port (on boot)

You can change the port by creating a file named /etc/lemon and adding the following content to it:

export PORT=1337

The init.d-script will look for the file and in case it was found source it.

Port (manually)

PORT=1337 ./lemon.sh

Integrations

GitHub Webhooks

First, make Lemon's port (e.g. 20001) accessible from the internet. You'll probably need to add a NAT rule to your firewall/router or fire up ngrok or something like that. Then, set up hooks on the GitHub repos (https://github.com/mrusme/<REPO>/settings/hooks) or organisations (https://github.com/organizations/<ORG>/settings/hooks) that you'd like to receive notifications for. For the Payload URL, use http://<YOUR-DNS-NAME>:<FORWARDED-PORT>/github. As Content type use application/json. The secret is not necessary (yet). Also, configure the webhook to Send me everything and don't forget to check the Active checkbox. That's it. You should be receiving notifications for at least a handful of implemented GitHub events.

IFTTT

You can create all sort of notifications using IFTTT's Maker Webhooks. Configuration is pretty easy:

Build your IFTTT rule by specifying the If this service and using Webhooks as then that service. Configure the webhook like this:

Zapier

Like with IFTTT, you can send webhooks from Zapier to Lemon. Configuration for Zapier is pretty easy as well:

Build your Zapier zap and use Webhooks as an action. Configure the webhook like this:

Pushover

Lemon provides an integration into Pushover using the Open Client API. Therefor, a separate config needs to be created, which will be read from/written to by Lemon. See lemon-pushover.cfg for an example configuration. In order to activate the Pushover plug-in, the environment variable LEMON_PUSHOVER_CONFIG needs to be set to the location of your lemon-pushover.cfg, e.g. LEMON_PUSHOVER_CONFIG=/etc/lemon-pushover.cfg. Make sure that the file is read and writable by the user you run Lemon under! You can set that environment variable within /etc/lemon, just like with PORT (see above).

Lemon will register a new device in your Pushover account (named lemon). This device can be targeted by other Pushover clients and it will of course also receive all un-targeted notifications. Be aware that you'll need a Pushover desktop license in order to use this feature. However, they do provide a 7-day-trial for you to test it.

If don't want to fiddle around with DynDNS, NAT or ngrok in order to make Lemon's HTTP port reachable from GitHub, IFTTT, Zapier and other webhook providers, you can set up Lemon to only use Pushover, which doesn't require you to expose any port. The Pushover client implementation uses a websocket to connect to the Pushover API and retrieve notifications. It basically acts like a web browser, hence you'll be able to use it even within networks you have no/little control over.

Info regarding 2FA (2 Factor Authentication): For Pushover Open Client API integration, Lemon uses jonogreenz/py-pushover-open-client. However, this library did not natively support 2FA, but a PR was set to the author of the library to include a possibility for an initial 2FA authentication. This PR was accepted and is available since v1.3.0 of the library. If you need 2FA make sure you pip3 install the latest version of the library!

InfluxDB

In order to use InfluxDB, simply add the configuration to your /etc/lemon:

export LEMON_INFLUXDB_SERVER=your-influxdb-server.local
export LEMON_INFLUXDB_PORT=8086
export LEMON_INFLUXDB_UDP=1
export LEMON_INFLUXDB_DB=your-database
export LEMON_INFLUXDB_USER=you-user
export LEMON_INFLUXDB_PASS=your-user-password

API

You can also attach any other service by using the generic Lemon API, which is accessible through http://yourdns:20001/api. The body of the requests/webhooks should contain the following JSON:

{ 
  "icon": "icon-name-here",
  "text": "The text to be scrolled through after the icon animation finished"
}

You need to make sure that the icon name you specify actually exists within the icons/ folder and is a .png file. If you want to use the icon icons/docker.png, simply specify "icon": "docker" in the JSON.

By default, each icon animation is being repeated three times. However, you can override that by specifying an additional JSON parameter named icon_repeat, e.g.:

{ 
  "icon": "doom-bloody",
  "icon_repeat": 1,
  "text": "Game over!"
}

Animation cycle time can also be adjusted individually, in order to allow smoother playback of longer animations:

{ 
  "icon": "microsoft",
  "icon_repeat": 1,
  "icon_cycle_time": "0.01",
  "text": "Micro$oft"
}

The default font can be adjusted by specifying the text_font property. In order for this to work, the font needs to be available as .ttf file inside the fonts/ directory. Example:

{ 
  "icon": "psy",
  "text": "Oppa Gangnam Style!",
  "text_font": "Hack-Regular"
}

In order to be able to categorize notifications, in case InfluxDB is being used, a category can be passed via JSON:

{ 
  "icon": "twitter",
  "text": "New tweet!",
  "category": "twitter"
}

Testing

curl -X "POST" "http://raspberrypi:20001/ifttt" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "icon": "youtube",
  "text": "New video on YouTube!"
}'

Kudos to ...

• @pimoroni for their awesome hardware
• @source-foundry for Hack, the best Termin/Editor font there has ever been

"Let me tell you..."

Sure, tell me!