Plugin architecture
Wall-ink devices can display any image that a wall-ink-server sends them. Plugins are a way to organize delivering different kinds of images to wall-ink devices.
Currently there are plugins for displaying a day's schedule for a room, and for displaying static images. But other examples of plugins could be:
- A weather station
- Retail sales price labels
- Bus or other transportation schedules
- A weekly or monthly calendar of events
- A building directory showing locations of events or personnel
A plugin could be anything, as long as it makes sense to display the resulting image on an e-ink screen that is only updated periodically.
There are several plugins already included with the wall-ink-server.
The Example Scheduler plugin has several purposes:
- Allows testing of a scheduler plugin after server installation without any further configuration, API keys, etc
- Allows for troubleshooting when other scheduler plugins break due to API key issues, database connections, etc
- Serves as an example template for programming a new scheduler plugin
The example scheduler plugin uses the same image generation code as the Booked plugin and the Google plugin.
The Booked plugin is a scheduler plugin for the open source scheduler Booked. It allows a Booked resource to be displayed on a wall-ink device. The Booked plugin does not use the Booked API, but instead uses a direct "read-only" database account to the booked DB.
The Google Calendar plugin allows a google calendar to schedule a resource and have that schedule displayed on a wall-ink device. It uses the same engine as the example plugin and the Booked plugin to create images for the wall-ink devices. For an enterprise deployment, it is recommended to create a new Google account for the plugin API to interface with. Other Google accounts throughout your enterprise can share their calendars with this new Google account that is configured to work with the plugin. This way, many calendars from multiple Google accounts can all display calendar data, and only one API key and account needs to be configured in the plugin.
The iCalWeb plugin was created initially to interface with outlook, but it can be used with any other calendaring system that publishes a compatible iCal calendar to the web. It has been tested with Outlook / Exchange, Google Calendar, and various other public iCal formatted calendars. Installation, configuration, and other details are in a separate wiki article.
The static plugin can be used to display any image desired. The plugin rotates through a collection of images. These images could be created by a script, could be scraped from the web, or could be advertisements, announcements, directions, etc.
Collections of static images are located in the www/plugin_dependencies/static_images folder. Each folder in this static_images folder appears in the device manager as a separate resource. Devices using this plugin cycle through the images for a particular resource at the interval specified in the device manager. So for instance, if you created a folder in static_images named "cars" and put a picture of a Mustang and a Camaro in that folder, and selected that the pictures be changed every 30 minutes, all screens pointed to that resource would first show "camaro.jpg". Thirty minutes later at half-past the hour, all screens would simultaneously switch to showing "mustang.jpg". Images can be most standard formats, and some resizing of images is also handled by the server. Images will automatically be converted to pbm files and resized as needed to be displayed on the wall-ink devices. All devices pointing to a particular resource will display the same image at the same time and will change the images displayed at the same time.
The simple text plugin allows text generated from a php script to be dynamically written to a wall-ink device. This was created to allow server side errors to be displayed on wall-ink devices. One such example is if a new wall-ink device checks in with a wall-ink-server and the MAC address is not in the device manager, the following image is given back to the device.
Do note that the error.php resource of the simple text plugin is used to display server error messages from the wall-ink-server on wall-ink devices. If the simple text plugin is not active, or the error.php resource is modified, server error reporting to wall-ink devices may be affected.
Each resource in the simple text plugin is a php file in the plugin_dependencies/simple_text/ folder. The php files will automatically show up in the device manager if they are in that folder. Each php script could really be anything including, API calls to the weather, news, or whatever was desired.
A minimal php script is offered here, as an example. The plugin wants to know the font, the margin and the pointsize and the caption to display. Look at the other examples in the plugin_dependencies/simple_text/ folder for more complex implementations.
function getResourceConfig($config,$device) {
$simpleTextConfig = new StdClass();
$simpleTextConfig->font="DejaVu-Sans";
$simpleTextConfig->margin="25";
$simpleTextConfig->pointsize="24";
$display_text = "Wall Ink Simple Text Plugin\n";
$simpleTextConfig->caption=$display_text;
return $simpleTextConfig;
}
The font will need to be a font that is available on your web server. Also note that bitmap fonts will look better on low-resolution e-ink screens. The margin is the number of pixels of whitespace that will surround the text. The pointsize is the size of the font used. The caption is the text to display. It can contain "\n" newline characters to display multiple lines of text.
The only drawback of this "simple text" plugin, is that it really is limited to simple text. All text on the screen is limited to being the same font size and font. It would not be that hard to also create an ImageMagick "Pango" plugin if varying text sizes was important to your project.
An example xkcd plugin was created to show how to create a new plugin. It is not part of the GitHub repository, but is included here in the documentation as an example.
The first plugins created for the wall-ink server were specifically designed for scheduling rooms. Code was written to take a day's a schedule, in a simple text format, and create an up-to-date listing of what was happening in that room. Additional "scheduler" plugins can be created fairly easily by leveraging the existing code that takes text input for the day's schedule and creates a new image for the wall-ink devices on the fly.
The most difficult part of creating a scheduler plugin is writing a function that produces a daily schedule in text like this:
EB Team Room #224
Team 23 Meeting
2018-10-23 08:00:00
2018-10-23 10:00:00
Math Study Group
2018-10-23 11:00:00
2018-10-23 12:00:00
Physics Study Group
2018-10-23 12:00:00
2018-10-23 14:00:00
Farm Robot Group
2018-10-23 14:30:00
2018-10-23 16:00:00
Hybrid Rocket Project
2018-10-23 16:00:00
2018-10-23 18:00:00
That schedule will create up-to-date images throughout the day that look like this:
Scheduler plugins could easily be written to include other scheduling engines such as:
- Microsoft Outlook
- iCal etc...
Some layouts in the scheduler plugins have code to generate QR codes. This allows a wall-ink device to forward a phone browser directly to the URL to schedule the particular room of the device they are at. Scheduler plugins also allow for the name of a website to be displayed on the screen.
Wall-ink-server plugins need code to perform two main purposes
- Interface with the device manager website
- Create images to be displayed on a wall-ink device
A wall-ink device simply displays whatever image it receives from the wall-ink-server. It does however need to be sized correctly, and be in the format that the wall-ink device firmware can understand.
A plugin will need to be written in PHP to interface with the device manager, and will need code to generate an image to send to a wall-ink device. See the xkcd plugin case study for an walk-through tutorial on creating a new plugin. Most likely you will be able to use much of the existing code and simply tweak it for your own use. Altering layouts for the general scheduler is documented in the adding a new layout for schedulingGetImage article.