Raspberry Pi Information Radiator: Building The Dashboard

The fifth and final post in a series for building an information radiator using the raspberry pi, it describes how to take the working Dashing dashboard from last time and customize it for our own purposes. I briefly outline the basics of populating a dashboard with widgets and jobs and discuss issues specific to running dashing on the raspberry pi.

Widget Basics

The dashing website describes the basics of a widget in detail. Essentially, a widget is defined using three files: a small amount of html specifying data bindings for the delivered data, style information in a SASS scss file, and event handling code in coffeescript. Once a widget is defined, instances can be created by editing the dashboard's ERB file. You just create a div with a data-view attribute matching a widget's class name and a data-id that is used to route data to the widget. Data can be pushed to the widgets by submitting an HTTP POST to /widgets/<data-id> from an external job or application, or can be pulled using Dashing's job support. The web site describes how to get data into your widgets in more detail. 

Installing Widgets

Because widgets are usually just three files (or four with a job), Dashing comes with the ability to install the necessary files from a GitHub Gist. The installer uses the file extensions of the files of the gist to tell whether the file should be placed under widgets/ or jobs/, as you can see from the Dashing source code. You do this by using the 'install' command followed by the gist id of the widget. For example, the asana tasks gist is https://gist.github.com/willjohnson/6334811 or gist 6334811. To install the widget, we run:

 $ dashing install 6334811  
    create widgets/asana_tasks/asana_tasks.coffee  
    create widgets/asana_tasks/asana_tasks.html  
    create jobs/asana_tasks.rb  
    create widgets/asana_tasks/asana_tasks.scss  
 Don't forget to edit the Gemfile and run bundle install if needed. More information for this widget can be found at https://gist.github.com/6334811  

As you can see, the command installs the files in the proper places and instructs you to continue with other widget-specific installation steps manually. Note that this does not add the widget to a dashboard. It only installs the widget as an available type. You still have to edit your dashboard ERB file to include a widget of the appropriate data-view type and data-id for the job.

Widget Declaration and Layout

Once the widget is installed, we can include it in our dashboard. We simply edit the dashboard ERB file under dashboards/ to include something like the following:

   <li data-row="1" data-col="3" data-sizex="1" data-sizey="2">  
    <div data-id="asana_tasks" data-view="AsanaTasks" data-title="Today's Tasks"></div>  
    <i class="icon-check icon-background"></i>  
   </li>  

As previously mentioned, the important parts for the widget definition are the data-id and data-view. These relate the div to the data event name and widget type, respectively. You can see here that you can also provide data to the widget directly by specifying it with a data- prefix. Here, the title of the widget is set directly rather than using data from a data event.

The li element is to specify how to layout the widget, these inform the location and size of the widget in the dashboard. The data-row and data-col attributes specify the cell that the widget's upper-left corner will be start in. The data-sizex and data-sizey attributes specify the width and height of the widget in grid cells. You can read more about how to position widgets from the Dashing site.

Further Customizations

Armed with the basics, you can create a dashboard customized specifically for your needs. However, I ran into a few issues I feel warrant additional treatment. Some are specific to running on the raspberry pi.

Separating Configuration from Source Code

The first issue I wanted to address was removing the somewhat sensitive information like API tokens and authentication credentials from source control. I found that the widgets typically didn't bother doing this. However, I wanted to publish the complete development history of my dashboard, so I needed to address this up front. I ended up using the dotenv gem to put settings into the ENV array. I then just changed the widgets to use ENV[setting] rather than hard-coding the setting directly in code.

I did run into one snag with this approach. Initially, I loaded the environment directly in the rackup file, config.ru. However, I found this did not load the settings into ENV in time for all the necessary code. Specifically, jobs that referenced ENV outside of the scheduled routines could not see their settings. Looking at the source code, I found that Dashing loads files under lib/ before it loads the jobs. By putting the environment initialization in a file under lib, settings were loaded and accessible as I initially expected. 

Installing Native Gems Through APT

Another snag I ran into was that certain ruby gems needed native extensions. Since these are architecture dependent they need to be compiled for the raspberry pi's ARM processor. While it eventually worked, the time it took to install was extremely long. I found that I didn't have to do this. Raspbian includes packages for certain common ruby packages. Before installing gems that a widget requires through gem install or bundler try installing it through APT first. For example, I installed nokogiri directly like so:

 $ sudo apt-cache search nokogiri  
 libnokogiri-ruby - Transitional package for ruby-nokogiri  
 libnokogiri-ruby1.8 - Transitional package for ruby-nokogiri  
 libnokogiri-ruby1.9 - Transitional package for ruby-nokogiri  
 libnokogiri-ruby1.9.1 - Transitional package for ruby-nokogiri  
 ruby-nokogiri - HTML, XML, SAX, and Reader parser for Ruby
$ sudo apt-get install libnokogiri-ruby
... 

Slow CSS Transitions

Finally, I found that many of the widgets used CSS3 transitions to make the widgets look more visually appealing. However, these transitions did not render well on the raspbery pi. Instead of looking smooth and visually appealing, they often just delayed the widget from showing up quickly. I ended up modifying the offending widgets to not using transitions.

Summary

That about covers the basics and a few snags you might encounter while developing a dashboard for the raspberry pi. I have made the complete source code for my own dashboard available on my github account. Have fun developing your own!