How to build a public dashboard with Geckoboard


0. Introduction

Geckoboard is an online software that helps everyone to create public dashboards around your own metrics. The key features we find are: really intuitive drag and drop interface to setup the dashboards, full screen mode to easily share dashboards on TV or any king of screen, really clean and modern aspect of the dashboards we can build and a really smooth and faultless functioning.

This easy tutorial quides you through the process of building a public dashboard with Geckoboard, sending data from your Altair SmartWorks account. In this tutorial we will build a similar dashboard to the one created with Javascript and CORS in this project: Altair SmartWorks Meteo.


1. Get your Geckoboard Account

Geckoboard is a paid service but a free 30 days trial is offered. Once registered (no credit card required) and logged-in, we are directly redirected to the drag and drop interface where we can build our dashboards.


2. Creating a Dataset

Geckoboard widgets can show metrics from several sources. Some integrations with popular platforms are offered but for this tutorial we are going to send the data collected by our meteo station to the Geckoboard account using their API.

The first step to use the data API is to get the API Key from the “Account details” page. You can access this page by clicking on the user icon on the top right corner of the screen:

The next step is to create a Dataset, that is to say, a schema that will let Geckoboard know what form your data takes. The number os Datasets you can create is unlimited. It's possible to include up to 10 different fields in a dataset, so one dataset is enough for our purpose.

Following the Geckboard docs we have to use the API to create the Dataset, sending a json schema to define it. We can use a “Poster” like tool, curl or any other tool supporting “basic auth” to make the request. For example, we are going to use the Altair SmartWorks Console with this code:

Don't forget to change the dummy Geckoboard API Key (def auth = ["user":"XXXGECKOBOARDAPIKEYXXX"]) and modify the Dataset name in the url ( if you don't like the one used. As you can see we are creating a field for each data present in the Meteo Station streams. You can dig in the API definition for deeper information.


3. Sending Data to Geckoboard

We have enhanced the listener creation process with our Flow Tool.

We are going to post to our new Dataset every data from our meteo station streams. Once again we are going to use Geckobaord API, posting data from an Altair SmartWorks Listener each time a stream arrives.

In the Flow editor we'll only need to drag & drop a "function" node and add our custom code since this tutorial is not intended to explain the details of the Flow Tool. For a deeper vision of the tool please read its documentation or our "How to create a listener" tutorial.

  • Flow designer: function node

After saving it, your listener will look something like this.

  • Resulting listener

Once again don't forget to change the dummy API Key. Take care: Datetime fields must be formatted as ISO 8601 strings, use “POST” method instead of “PUT” and the json data posted must respect the Dataset schema.

You can wait some time to let the meteo station send some readings to Altair SmartWorks, therefore to Geckoboard Dataset thanks to our new listener, and continue with the next step.


4. Adding the Widgets

You can easily add widgets to your dashboard by clicking on the “Add widget” button:

On the “Data Sources” screen you must select “Datasets” and next select the previously created Dataset “meteostation”.

On the next screen you can build the widget you will add. The first thing you'll notice in the setup screen is that there’s an initial line chart based on the data provided. This is the default visualization and it will work if your data can be used to plot a line chart. You can change it by selecting a different widget from the visualization selector. In the Widget Setup Area you will set up and define how to visualize the dataset. Any changes to this section will be displayed on the live preview screen to the right. This area is broken into two sections: Build and Fine-tune.

For this first Widget we will select “Wind speed” as the showed metric, “Average” aggregation and “Date” as the X-Axis. We will bucket it by minute (“Bucket: m”). On the right side of the screen (graph preview) we can change the widget title and the space the widget will take (“2wx1h” = 2 width blocks x 1 height block).

For a more in-depth documentation of the widgets you can add you can visit the documentation. Don't hesitate to play with the setup screen! It's easy and everything is editable / erasable!

You can repeat this process for every metric you want to show in the dashboard.


5. Enhancing the Dashboard

We would like to show more information to our dashboard like the meteo station situation and the wind direction. As you can see there is no predefined widgets por this kind of representations, but we can use the Geckoboard “custom widgets”. These custom widgets work in a slightly different way: we can push / they can poll data directly to / from the widget. In our case we're going to push data to them from our Altair SmartWorks listener.

The first step is to create both widgets by clicking the button “Add widget” and selecting “Custom Widgets” from the data sources list. We will use “Mapping” widget and “Text” widget for our purposes.

Map Widget:

In the setup screen of the mapping widget we will introduce the title, asign a 2x2 size, select “Push” method (as we will push the data from the Altair SmartWorks listener) and the region “Europe” / “Spain”. We will click on the creation button.

Once created we have to edit the widget by clicking on his right bottom icon. You will then see the setup screen again but two new important fields are now present: “Push URL” and “Widget key”.

Using the field “Push URL” we can update our Altair SmartWorks listener adding the next code to the "function" node we used in the previous step:

As you can see we are posting directly to the widget some json formatted data containing latitude and longitude of our meteo station. The format is specified in the mapping widget documentation. Take care of introducing the Geckoboard API Key in the first field of the body json (remember: we defined it in the first lines of the listener code).

Wind Direction Widget:

We repeat the steps made with the map widget: create a text custom widget, edit, copy the push URL and modify our listener code.

Again, we update our Altair SmartWorks listener adding the next code to the "function" node:

As you can see we are posting some text containing a Font Awesome


6. Final Result

To sum up: we created a Dataset in Geckoboard to collect every data sent by our meteo station, we created a listener in Altair SmartWorks to push data to the Dataset and we built a dashboard using some predefined widgets and two custom widgets.

The complete Listener code is:

  • Name: The name that you prefer
  • Description: The description that you prefer
  • Entity type: Device
  • Entity id: Your device id
  • Event to listen: Event Data Received
  • The custom code stored into our "function" node:

After adding some decoration images, some more line charts, some number widgets with the last readings and the two custom widgets we just explained the result of our dasboard in full screen mode is:

Remember you can share your dashboard via a direct link or inviting users via email by clicking on the “Share” button of the main screen.


7. Geckoboard Limits

Geckoboard is a data visualisation tool, not an analysis tool or data warehouse. Don’t use Geckoboard as a Data Base as each dataset can contain up to 5000 records. When a dataset exceeds the record count limit the oldest records (by insertion time) will be removed.

Each Geckoboard account is limited to 100 datasets. When the number of datasets is reached, no more datasets can be added. You can delete datasets via the API. Each PUT or POST request will accept 500 records, which includes both new records and updates to existing records.

There is basic rate limiting on the API. This restricts you to 60 requests per minute for your API key. If you exceed your limit, the API will return a 429 status and an error message.


8. From here on: Enhancing the Project

Now you know how to send data to Geckoboard from a Altair SmartWorks account and create a basic dashboard. But you can enhance this project in many ways:

  • Try to add some more useful widgets and learn how to use them. For a meteo station scenario a good idea would be to include a “Leaderboard” with top wind speed readings, for example.
  • Try to improve widgets functionality adding filters, goals or include a comparison on various metrics.
  • Try to create the Datasets directly from a Altair SmartWorks Listener and create a dashboard for diferent devices, projects, customers, etc.