piminder 1.0.6

Piminder is a special network messanging service for status alerts.

Piminder

A minimal-functionality heads-up-display/dashboard utility for the Raspberry Pi, premised on the Pimoroni GFX Hat. This utility operates a small Flask-based RESTful API and provides two helper modules, monitor and helpers, allowing local scripts and cron jobs to display messages on the HAT in a structured way. Initial development is by Arcana Labs. Development is very casually ongoing, with minor incremental improvements as they become desired within the lab.

Fitness for Risk

Piminder is intended for use as a small-scale monitoring utility in a lab/private subnet capacity only. It is not hardened for or intended to for use with a WAN or direct exposure to the internet, and should be protected by a reverse proxy and other traffic shaping rules at all times if present on such a network. The release version, 1.0 and later, includes TLS capabilities. It is strongly recommended you read the documentation fully before configuring and using this product.

System Requirements

It is supposed that the local versions of Raspbian and Python 3 are up to date. The test article also used an up-to-date version of Mariadb. Naturally, the GFX hat is also a requirement as the monitor will not work with any other display.

Recommended Usage Instructions

Note: Apart from SECURITY.md, all referenced documentation is in the documentation folder.

1. Read the SECURITY.md and NETWORKING.md documentation thoroughly.
2. Follow the instructions in SERVICE_SETUP.md to install and configure Piminder's service on its target device and create your first auth credentials
3. pip install Piminder on any system where you wish to use Piminder_helpers or Piminder_monitor.
4. Configure the monitor and establish it as a service on the host pi based on the instructions in MONITOR_Setup.md

Using Helpers

The helpers module exposes a class constructor and several convenience functions to allow scripts to more easily work with the Piminder API.

To use:

1. instantiate a PiminderService object using the necessary configuration details:

somehandler = Piminder_helpers.PiminderService(username, password, hostname, hostport, job_identifier)

2. use the .minor(), .major(), and .info() methods of that object to post messages directly to the API, with the message as a string of arbitrary length.

Using the APIs Directly.

The Piminder API is a REST-like API exposed via flask, at $servicehost/api/messages/ and $servicehost/api/users. The API expects basic authentication.

Interacting with Piminder

Careful observation of the GFXHat will note that each of the six buttons is individually marked. When Piminder is in operation, these buttons perform the following functions:

• "^" will scroll the current message upward.
• "v" will scroll the current message downward.
• "<" will mark the message as read.
• "-" will switch to the previous message.
• "+" will switch to the next message
• "Circle-Dot" will delete the currently displayed message.

Each of these buttons also has a corresponding LED:

• "^" indicates that there is more to this message if you scroll up.
• "v" indicates that there is more to this message if you scroll down
• "<" indicates this message is unread
• "-" indicates there is a message before this one.
• "+" indicates there is a message after this one.

The LCD is backlit, and the colour is used to indicate message severity. By default, this is green for info, yellow for minor, and red for major. These values can be changed in /src/monitor/monitor.conf by providing a hex colour code in the HTML-standard format, eg #123456.

Special Font Characters

The font is a UTF-8 font, though the full keyspace is not defined. Characters 32-126 (the normal printing range) is defined. In addition, 12 special characters are defined:

Python Escaped String Literal	Character Description
\u0082	Envelope Icon
\u0081	Progress Bar, Left End, Empty
\u0082	Progress Bar, Left End, Filled
\u0083	Progress Bar, Middle, Empty
\u0084	Progress Bar, Middle, Full
\u0085	Progress Bar, Right End, Empty
\u0086	Progress Bar, Right End, Full
\u0087	Major Severity Icon (! in Triangle)
\u0088	Minor Severity Icon (? in Square)
\u0089	Info Severity Icon (i in Circle)
\u00BA	Elipsis (...)
\u008B	Clock Icon